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INTRODUCTION 

Programming RSX-11M in MACRO is intended for MACRO-11 
programmers who use services of the RSX-11M operating system 
beyond those provided by the MACRO-11 programming language itself. 
This course describes the various services and how to use them 
from a task which you write. 

This course is self-paced, which means that you learn at 
whatever rate is comfortable for you. 

Instead of a teacher, you have a course administrator and a 
subject matter expert. In some cases, the same person can perform 
both functions. The course administrator manages the mechanics of 
the course and makes sure you have easy access to the system and 
the on-line course materials. As you finish modules, s/he records 
your progress. The subject matter expert helps you if you have a 
technical question. Before you consult the expert, however, read 
the course materials and references in an effort to answer the 
question yourself. 

This Student Guide covers the following topics: 

• Course prerequisites 

• Course goals (and Nongoals) 

• Course organization 

• Course map description 

• Course resources 

• How to take the course 

• Personal Progress Plotter 
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PREREQUISITES 

To be prepared for this course, you must have taken the 
following DIGITAL courses, or you must have equivalent experience. 

1. RSX-11M Utilities and Commands. Specifically, you must be 
able to logon/logoff, edit files, and develop/run/debug 
programs under RSX-11M. 

2. Programming in MACRO-11. 

COURSE GOALS AND NONGOALS 

On completion of this course, you should be able to write 
tasks which: 

1. Use executive directives 

2. Perform intertask communication and coordination 

3. Perform synchronous and asynchronous I/O operations 

4. Use overlays 

5. Use memory management facilities to communicate between 
tasks and make more effective use of available memory 

6. Use File Control Services to create and maintain files. 
This course does not teach the following: 

1. The PDP-11 instruction set and the MACRO-11 programming 
language 

2. The Digital Command Language (DCL) or Monitor Console 
Routine (MCR) 

3. The program development cycle. 



4 



STUDENT GUIDE 



COURSE ORGANIZATION 

This course is self-paced for independent study. The course 
material is structured in modules. Each module is a lesson on one 
or more skills required to fulfill the course goals. A module 
consists of: 

• An introduction to the subject matter of the module 

• A list of objectives, which describe what you should 
achieve by studying the, module 

• A list of resources that provide reference materials and 
additional reading for the module 

• The module text, including explanatory text, figures, 
tables, examples, and references to readings in the 
manuals 

• Learning activities (for some modules) , consisting of 
reading assignments or written exercises which are 
essential to your learning the material 

• Written and/or lab tests and exercises (bound separately) 
which you can use to measure your achievement. Solutions 
are provided for all exercises. 

The course is bound in two volumes. The first volume 
contains this student guide, the 10 modules (except for their 
tests/exercises), the appendices, and a glossary. The second 
volume contains the tests/exercises for each module. 



COURSE MAP DESCRIPTION 

The course map shows how each module relates to the other 
modules and to the course as a whole. Before beginning a specific 
module, it is recommended that you first complete all modules with 
arrows leading into that module. These prerequisite modules 
present material necessary to understanding the module you are 
about to study. 

If you have no preference, study the modules in numerical 
order, 1 through 10. 
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COURSE MAP 
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COURSE RESOURCES 

Required References 

1. IAS/RSX-ll I/O Operations Manual ( AA-M 1 7 6A-TC ) 

2 * IAS/RSX-ll System Library Routines Reference Manual 
(AA-5580A-TC) 

3. RSX-11M Mini-Reference ( AV-5570D-TC) 

4. RSX-11M/M-PLUS Executive Reference Manual ( AA-L675A-TC) 

5. RSX-11M/M-PLUS I/O Drivers Reference Manual ( AA-L677A-TC) 

6. RSX-11M/M-PLUS Task Builder Manual ( AA-L680A-TC) 

Optional References 

1. PDP-11 MACRO-11 Language Reference Manual ( AA-5075B-TC) 

2. PDP-11 Processor Handbook (EB-19402-20/81) 

3. RMS-11 User's Guide ( AA-D538A-TC) 

4. RMS-11 MACRO-11 Reference Manual ( AA-H683A-TC) 
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HOW TO TAKE THE COURSE 

Because this is a self-paced course, you determine how much 
time to devote to each subject. You can pass quickly over 
familiar topics. You can spend more time on topics which are of 
interest to you, or which you can use often in your job, and less 
time on topics which have little use in your job. 

Each time you are ready to begin a new module, first read the 
introduction and the objectives. If you feel that you already 
understand the material in the module, you can go immediately to 
the tests/exercises for that module. If you don't understand much 
of the material, read the module. If you understand some of the 
concepts but not others, just look over the program examples for 
the concepts you understand. Read the text and study the examples 
for concepts you don't understand. The text explains new concepts 
and refers you to related readings in the manuals. The program 
examples provide working examples which show you how to apply the 
concepts . 

Some of the readings in the manuals are required and others 
are optional. Required readings are contained in learning 
activities and are indented to set them apart from the module 
text. These readings are required because they cover material not 
otherwise covered in this course. The optional readings are 
mentioned within the module text and are designed to help you in 
two ways. First, they teach you more about a given topic. 
Second, they offer another explanation in case you have trouble 
understanding the explanation in this course. 

In addition, you will need the manuals to look up the 

specifics involved in invoking the various services. This is 

especially true for the executive directives, system library 
routines, and File Control Service calls. 

Keep the module objectives in mind. If a skill is listed as 
an objective, be sure to master it. Later modules may depend on 
this skill . 

The module text contains many example programs to show you 
how to use the skills you are learning. All of the example 
programs in this book should be available on-line. The standard 
location for these files is UFD [202,1] on your system disk. 
Check your system and if the files are not located there, check 
with your course administrator to find out where they are located. 
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Do not modify the files in UFD [202,1] or in their original 

location. Instead, copy the files you plan to use to your own UFD 

and use them there. In that way, the original files in UFD 
[202,1] will remain intact for other students. 

Each example program contains the following: 

• Source code, with line numbers added 

• A sample run session 

• Bulleted items which are described in the text. 

Line numbers have been added to the source code to ease 
referencing during a group discussion. These line numbers are not 
part of the actual source file. The source code also contains the 
name of the file which contains the code on-line. Following this 
is a brief description, telling what the example does. Any 
special assemble and task-build instructions, and any special 
install and run instructions follow this. Only special, 
nonstandard instructions are included. The code itself includes 
line comments plus some additional comments. 

The sample run session shows what happens during a typical 
run of the task. Any special install and run instructions are 
shown in the run session. 

The bulleted items match the example notes in the text, which 
describe the code in more detail. Study the examples and the 
notes that describe them carefully. 

In the module on Using File Control Services, many of the 
examples create output files. A dump of any created file follows 
the run session. The file dumps were created using the DMP 
utility. 

If the examples are available on-line, assemble and 
task-build them, and then run them. This will help you to 
understand the examples better. Many of the tests/exercises ask 
you to make minor changes to existing examples, and then run them 
again. Do the tests/exercises for a module in the Tests/Exercises 
book only after you have done all of the reading and have run the 
example programs. If you prefer, you can do them as soon as you 
cover the necessary material in the module. The same 
Tests/Exercises book is used in this course and the Programming 
RSX-11M in FORTRAN course. Do all tests/exercises except those 
which specifically say in FORTRAN. All exercises have solutions 
in the Tests/Exercises book. In addition, any solutions involving 
programs should be available on-line, in UFD [202,2]. Compare 
these solutions to your own. 
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If you have mastered the module objectives, ask your course 
administrator to record your progress on your Personal Progress 
Plotter, You will then be ready to begin a new module. If you 
haven't yet mastered the module objectives, return to the module 
text for further study. 

With a self-paced course, it is impossible to give a schedule 
that applies to all students. The amount of time that students 
spend on a module depends on both their experience and their 
interest in the topics in that module. Use Table 1 as a guide 
when you set your schedule. 

In addition to the 10 modules, the Student Workbook contains 
several appendices, plus a glossary. The appendices are: 

Appendix A - Supplied Macros. This appendix contains 
documentation on how to use the macros supplied with the 
course. In addition, it includes the source code for all of 
the macros and any subroutines which they require. 

Appendix B - Conversion Tables. This appendix contains a 
table for converting between decimal and octal, and among 
words, bytes, and memory blocks. It also contains a table 
for converting from active page registers (APRs) to virtual 
addresses . 

Appendix C - F0RTRAN/MACR0-1 1 Interface. This appendix 
contains an explanation of the techniques which you should 
use to write a FORTRAN callable subroutine in MACRO-11. It 
also explains how to call such a subroutine from MACRO-11. 

Appendix D - Privileged Tasks. This appendix contains a 
description of the various types of privileged tasks 
supported under RSX-11M, and how to create them. 

Appendix E - Task Builder Use of Psect Attributes. This 
appendix contains a description of the effect of Psect 
attributes on how the Task Builder collects together 
scattered occurrences of program sections. 

Appendix F - Additional Shared Region Topics. This appendix 
contains several additional shared region topics. They are: 
overlaid shared regions, referencing multiple regions from a 
single task, interlibrary calls, and cluster libraries. 
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Appendix G - Additional Examples. This appendix contains the 
source code for any program examples which are required for 
the Tests/Exercises but are not included elsewhere in the 
Student Workbook. These examples should also be available 
on-line, under UFD [202,1]. They are included here in case 
they are not available on-line on your system. 

Appendix H - Learning Activity Solutions. This appendix 
contains the solutions to any Learning Activity questions in 
this course. After you do a Learning Activity, check your 
answers against those provided. 
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Table SG-1 Typical Course Schedules 



Module 
1. 



2. 
3. 

4. 



Using System 
Services 

Directives 

Using the Qio 
Directive 

Using Directives 
for Intertask 
Comm unication 



5. Memory Management 
Concepts 



6. 
7. 
8. 
9. 



Overlays 
Static Regions 
Dynamic Regions 
File I/o 



10- File Control 
Services 

Totals 



More Experienced 
Student 

2.0 ho ur s 



5.0 hours 
4. hours 

5.0 hours 

2.0 hours 

5.0 hours 
4 . 5 hours 
4 . 5 hours 
2.0 hours 
6.0 hours 

40.0 hours of 
study and lab 



Less Experienced 
Student 

3.0 hours 



7.5 hours 
6.0 hours 

7.5 hours 

3.0 hours 

7.5 hours 
7.0 hours 
7.0 hours 
3.0 ho ur s 
9.0 hours 

60. 5 hours of 
study and lab 
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PERSONAL PROGRESS PLOTTER 



MODULE 


DATE 
STARTED 


DATE 

COMPLETED 


TIME 
SPENT 


SIGN-OFF 
INITIAL 


1. 


USING SYSTEM 
SERVICES 










2. 


DIRECTIVES 










3. 


USING THE QIO 
DIRECTIVE 










4. 


USING DIRECTIVES 
FOR INTERTASK 
COMMUNICATION 










5. 


MEMORY 

MANAGEMENT 

CONCEPTS 










6. 


OVERLAYS 










7. 


STATIC REGIONS 










8. 


DYNAMIC REGIONS 










9. 


FILE I/O 










10. 


FILE 

CONTROL 
SERVICES 
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USING SYSTEM SERVICES 



INTRODUCTION 

RSX-11M provides system services which perform many 
operations that are commonly needed by user-written application 
programs. Skillful use of these services can: 

• Improve the efficiency of your tasks, reducing size and 
execution time 

• Decrease the time it takes to code and debug your tasks 

• Increase the reliability of your tasks 

• Provide you with controlled access to system features 

• Benefit the overall performance of your system. 

The first step in learning to use these services is 
understanding what services exist, how you can request them from 
within your task, and how the services are delivered to you. 
These topics are explained in this module and the following 
module . 

OBJECTIVES 

1. To identify the facilities provided through system 
services 

2. To list the ways in which system services may be provided 
to a task 

3. To list the various system libraries and the facilities 
they provide. 

RESOURCES 

1. RSX-11M/M-PUJS Executive Reference Manual , Chapter 1 

2 . IAS/RSX-11 System Library Routines Reference Manual , 
Chapters 1 through 6 
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WHAT IS A SYSTEM SERVICES? 

An RSX-11M system service is a function or service performed 
for a running task. It is performed during the task's execution. 
The software which provides the service is either in the Executive 
itself or in other system supplied code. 



WHY SHOULD YOU USE SYSTEM SERVICES? 



To Extend the Features of Your Programming Language 

System services offer you additional features, not inherently 
a part of your programming language. Examples of this are: 

1. Accessing shared resources in a properly synchronized way 

2. Performing I/O operations in MACRO-11 

3. Coordinating among multiple tasks 

4. Controlling memory allocation and mapping 

5. Interacting with the Executive 

6. Performing often needed functions, such as: 

a. Numeric conversion of ASCII data typed in at a 
terminal to binary format for internal use 

b. Editing, and conversion, to produce suitable output 
messages which include data generated at run time. 



To Ease Programming and Maintenance 

DIGITAL provides the code to perform these services. 

Therefore, you will need less time to develop working programs. 

The supplied code has a well defined modular structure, which 
makes it easier to design your programs. 

The code for system services is well debugged. This makes it 
easier to debug and maintain programs, since there are fewer 
potential points of failure and only your written code needs to be 
debugged. When maintenance is required in the code for the 
supplied system services, patches are released with clear-cut 
installation procedures. 
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To Increase Performance 

The supplied code to perform system services is generally 
efficient MACRO-11, which assures minimum execution time. In 
addition, it is often possible to share the code among several 
different tasks, with minimal additional overhead. This can 
result in any or all of the following performance gains. 

• Increase in your task's throughput 

• Increase in your system's throughput 

• Increase in memory usage efficiency on your system 

• Decrease in your task's size 

• Increase in available space on mass storage volumes 



WHAT SERVICES ARE PROVIDED? 

The system services can be divided into a number of classes. 
For each, a few examples are given to show you the kinds of 
services which are available. 

Note that a number of these services which are provided to 
tasks parallel those provided to operators through DCL commands. 



System and Task Information 

You can obtain information from the system. For example, you 

can: 

• Obtain information about your task 

Its priority 

Its logical unit (LUN) assignments 

• Obtain information about a partition on the system 

- Its base address 
Its length 

• Obtain the current time and date 
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Task Control 

You can start up and stop tasks, and alter task states. For 
example, you can: 

• Request another task to run 

• Abort a task 

• Suspend or resume a task 

• Alter the running priority of an active task 

Task Communication and Coordination 

You can create a set of tasks that communicate with one 
another, as well as coordinate the interaction of the tasks. For 
example, you can: 

• Send data from one task to another. 

• Have one task notify other tasks that an event has 
occurred (e.g., that a job has been completed). 

• Have one task pass a command to another task, and have it 
obtain an indication from the other task about the status 
of the execution of the command. 



I/O Peripheral Devices 

You can interact with peripheral devices on your system. For 
example, you can: 

• Write data to or read data from a peripheral device. 

• Attach a device for exclusive use by a task. 

• Read or set variable characteristics of a device (e.g., 
for a terminal - baud rate or hold screen mode) . 



File and Record Access 

You can access files, including individual records within a 
file. For example, you can: 

• Create a file. 

• Read blocks from or write blocks to a file on a 
block-by-block basis. 
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• Read records from or write records to a file. The records 
may be of different lengths, and not exactly one block 
long. 

• Extend or truncate an existing file. 

File and Record Access Systems 

The two access systems available under RSX-11M are File 

Control Services (FCS) and Record Management Services (RMS) . Both 

offer an interface between tasks and the Files-11 structure used 
to maintain disk directories and files. 

FCS is the standard access system supplied with RSX-11M. 
Many of the utilities (e.g., PIP, EDT, the Task Builder) use FCS 
for their file interface. RMS offers all of the FCS functionality 
plus capabilities not available with FCS, such as indexed files 
(records that are accessible by a key field value) and more 
sophisticated file sharing. A more complete discussion of the 
facilities offered by FCS and RMS, and a comparison of the two, 
appears in Module 9, on File I/O. 



Memory Use 

You can use system services to control the amount of memory 
your task uses or to permit several tasks to share an area of 
memory. For example, you can: 

• Run a task in less memory than its total size, by using 
overlays to load only needed pieces of the program at one 
time . 

• Allocate space in memory for a temporary work buffer, and 
then return that space to the system when the task is 
finished using it. 

• Share a data area in memory among several tasks. 

• Share a single copy, in memory, of a commonly used 
subroutine among several tasks. 
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OTHER SERVICES AVAILABLE 

You can use system services to perform often needed 
functions. For example, you can: 

• Save and restore all or a subset of the registers when 
writing a subroutine. 

• Perform extended integer and double precision 
multiplication and division. 

• Convert data from ASCII to internal binary. 

• Convert and format output data produced at run time into 
printout and/or display messages. 

These services are generally supplied as subroutines located 
in the system object library (LB: [1,1] SYSLIB.OLB) . Most of the 
subroutines are documented in the IAS/RSX-11 System Library 
Routines Reference Manual . A few of the subroutines will be 
covered in detail in this course. However, most will not. Table 
1-1 gives examples of specific functions performed by some of the 
subroutines . 

LEARNING ACTIVITIES 1-1 

1. Read the preface to the IAS/RSX-11 System 
Library Routines Reference Manual . 

2. Look through Chapter 9 of the same 

See what functions are offered and how the 
subroutine calls are made. Also, familiarize 
yourself with the organization of the book so 
that you can easily find a subroutine to 
perform a specific function. 
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Table 1-1 Examples of Use of Other Services 
User Task Requirement Solution Using System Services 



A user written subroutine 

must save and restore 

the registers R0 through R5 



User wants to convert a 
number input from the 
terminal (in decimal 
ASCII) to binary for 
program use. 

User wants to output a 
message that includes data 
calculated at run time 
(e.g., 3 + 4 = 7, where 
the values aren't known 
until run time) . 



On entry to the subroutine, call 
$SAVAL. On return to the caller, 
the registers will be restored 

iiillB^ 

(There are other routines for 
saving R0 through R2, Rl through 
R5, and R3 through R5.) 

Call the subroutine $CDTB, pass- 
ing it a pointer to the first 
ASCII character. On return, Rl 
contains the converted value. 



Rather than using a number of 
calls to a routine to convert 
each value to ASCII, a general 
purpose editing routine $EDMSG 
(Edit Message) is available. 
$EDMSG takes a template string 
and converts and fills in the data 
values, creating an output 
string suitable for display. 
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HOW SERVICES ARE PROVIDED 

Services are provided using two different methods. 

1. The Executive is invoked by the task to perform the 
service (an executive directive) . 

2. The code to perform the service is placed directly into 
the task. 



Executive Directives 

Figure 1-1 shows how the first method works. The following 
notes are keyed to the figure. 

O Tne user task makes a service request and invokes the 
Executive . 

Q The Executive takes control and performs the service. 

Calls device drivers as needed 
Requests other tasks as needed 

Q The Executive returns control to the user task, at the 
instruction following the service request. 

Figure 1-2 shows a more complex version of method 1. In this 
case, Task A and Task B interact through the Executive. 

Task A starts up and at some point needs Task B to do some 
work, for example, perform a calculation. Task A sends the data 
to Task B, requests that Task B run, and then waits until Task B 
sends back the answer. Task B starts running, performs the 
calculation, and then sends the answer back to Task A. Task B 
also notifies Task A that the job is finished. Task A then starts 
up again and uses the answer. The steps outlined above for Figure 
1-1 would actually be used several times in this example. 
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EXECUTIVE 








Q CODE TO 
SERVICE 


* F11ACP 




I/O 

DRIVERS 




EXECUTIVE 






« 


DIRECTIVE 


* ♦OTHER TASKS 



T 



TASK 



^EXECUTIVE DIRECTIVE 
INVOCATION 
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ure 1-1 Using Executive Directives to Service a Ta 



Q RETURN OF 
STATUS FROM 
EXECUTIVE 
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EXECUTIVE 




CODE TO 




SERVICE 




DIRECTIVES 




1 1 




1 r "l 1 



TASK A 



EXECUTIVE DIRECTIVES 



| DATA FROM TASK A ] 



RESULTS FROM 
TASK B 



TASK B 



EXECUTIVE DIRECTIVES 



Figure 1-2 



Using Executive Directives to Receive Services 
from Other Tasks 
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Code Inserted into Your Task Image 

The second method for providing system services is 
illustrated in Figure 1-3. The code to perform the service is 
extracted from a system library and inserted directly in the user 
task. For system macros, the machine code resulting from the 
macro expansion is executed in place. For system subroutines, the 
subroutine call results in a transfer of control to the subroutine 
code, located in another part of the user task. 

Certain services must be provided by invoking the Executive. 
Any service which involves synchronization or access to shared 
resources must be coordinated by the Executive. For example, if a 
request activates another task, the Executive must enter the task 
in the active task list, which sets the task up to compete for 
memory space and then CPU time. It is much easier to have the 
Executive coordinate all the tasks, rather than require that each 
task check with every other task before using a shared resource. 
Also, any activity that involves communication or coordination 
among multiple tasks usually must be performed by the Executive. 

Placing the code in the user task is appropriate for a 
service which is performed independently by a task. For example, 
if a task converts an ASCII decimal value which is input at a 
terminal to binary for internal use, there is no need for the 
Executive to coordinate that activity. It does not affect shared 
resources or other tasks. 

If a service can be provided with code inserted in the task 
and that service is needed often by a number of different tasks, 
it is possible to share one copy of the code among several tasks. 
Using special techniques, often used subroutines can be collected 
together and a single copy of each subroutine can be shared in 
memory among several tasks. The procedure for producing and using 
a shared collection of subroutines, called a resident library, is 
discussed in the Static Regions module of this course. 

Some of the services discussed in this course are provided by 
making special requests when you task-build your task. In some 
cases, the Task Builder transparently places code directly in your 
user task. In other cases, it sets up your task in a special way 
to provide the service. We will discuss the techniques for 
accessing services with the Task Builder in later modules. 
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FROM SYSTEM MACRO 
LIBRARY AT ASSEMBLY TIME 



FROM SYSTEM OBJECT 
LIBRARY AT TASK-BUI LD TIME 



TASK 




MACRO- EXPANSION 




SUBROUTINE CALL 






SUBROUTINE ENTRY POINT 






RETURN 







TK-7514 



Figure 1-3 Code Inserted into Your Task Image 
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SYSTEM LIBRARIES 

Table 1-2 contains a list of the libraries which are used 
during program development of a task using system services. Thev 
are usually located in LB: [1,1]. RSXMAC.SML is the system macro 
library searched by default by the MACRO-11 assembler. SYSLIB.OLB 
is the system object library searched by default by the Task 
Builder. J 



Library 
RSXMAC.SML 



Table 1-2 Standard Libraries 

Languages 

Using Library 

( MACRO/ FORTRAN ) Contents 



MACRO-11 



SYSLIB.OLB 



MACRO-11 
FORTRAN 



Executive directive 
calls for MACRO-11 



Storage and 
symbol definition 
macros to support 
executive directives 

FCS calls, 
storage and symbol 
definition macros 

Executive directive 
calls for FORTRAN 



FCS subroutines 

Other file access 
routines 

Command retrieval 
and parsing 
routines 



Notes 

Default macro 
library for 
the MACRO-11 
assembler 



Default object 
library for 
Task Builder 



Assorted conversion 
routines, arithmetic 
routines, memory 
management routines 
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Table 1-2 Standard Libraries (Cont) 



Languages 
Using Library 
(MACRO/ FORTRAN) 



Library 

RMSMAC.MLB MACRO- 11 

RMSLIB.OLB MACRO-11 

FOROTS.OLB FORTRAN IV 



Contents 

RMS calls, storage 
and symbol defini- 
tion macros 

RMS subroutines 

FORTRAN IV Object 
Time System (OTS) 



F4P0TS.0LB FORTRAN IV-PLUS FORTRAN IV-PLUS OTS 
FORTRAN-77 FORTRAN-77 OTS 



Notes 



Optional soft- 
ware may be 
included in 
SYSLIB.OLB 

Optional soft- 
ware may be 
included in 
SYSLIB.OLB 
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Table 1-3 contains a list of the shareable resident libraries 
which may also be on your system, depending on your installation. 
You will learn how to use these resident libraries in Module 7, on 
Static Regions. Check with your system manager to find out 
whether the preferred method of including these routines is 
through linking the code into your task image or using the 
resident libraries. 



Table 1-3 Resident Libraries 



Resident 
Library 

FCSRES.TSK 



Routines 
Extracted from 

SYSLIB.OLB 



Comments 

Generally contains most 
FCS routines 



FORRES. TSK 
F4PRES.TSK 

RMSRES . TSK 



RMSSEQ . TSK 



FOROTS.OLB 
F4P0TS.0LB 

RMSLIB.OLB 



RMSLIB.OLB 



May contain all or 

some FORTRAN OTS routines 

Full-functionality RMS 
resident library 

RMS resident library for 
sequential access only 



Now do the tests/exercises for this module in the 
Tests/Exercises book. They are all written problems. Check your 
answers against those provided in that book. 

If you think that you have mastered the material, ask your 
course administrator to record your progress in your Personal 
Progress Plotter. You will than be ready to begin a new module. 

If you think that you have not yet mastered the material, 
return to this module for further study. 
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DIRECTIVES 



INTRODUCTION 



Once you know the various system services available, you need 
to know how to write programs which use them. This module 
explains more about the services available through executive 
directives and how to make various directive calls. 



OBJECTIVES 

1. To write programs in MACRO-11 which use directives 

2. To use information returned by the Executive to perform 
error checking 

3. To use event flags and asynchronous system traps (ASTs) 
with directives. 



RESOURCES 



1. RSX-11M/M-PLUS Executive Reference Manual , Chapter 1 and 
2, and specific directives in Chapter 5 

2. IAS/RSX-11 System Library Routines Reference Manual , 
Chapters 4 and 5 
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INVOKING EXECUTIVE DIRECTIVES FROM A USER TASK 



Directive Processing 

The sequence of steps outlined below details how a directive 
is invoked and processed. The following notes are keyed to Figure 
2-1. 



Executive Code User Code 

Q The user creates a Direc- 
tive Parameter Block (DPB) 
which contains all the 
information the Executive 
needs to process the dir- 
ective . 

Q Either the Directive 

Parameter Block itself or 
its starting address is 
pushed onto the stack. 

Q The user task issues an 
EMT 377 instruction, 
causing a trap into the 
Executive . 

Q A dispatcher routine 

retrieves the Directive 
Parameter Block, and 
checks it to find out 
which directive 
has been requested. 

Q The dispatcher routine 
calls the appropriate 
Directive routine to 
execute the directive. 
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Executive Code User Code 

Q After executing the dir- 
ective, the Executive 
returns control to the 
user task and returns 
directive status. 

The user task checks the 
directive status and takes 
appropriate action. 



Use macros in the system macro library, LB: [1,1] RSXMAC.SML 
to issue directives. 

Most directives pass control back to the user task. Certain 
directives by their nature do not pass back to the user task. The 
Exit Task directive, for example, causes the task to exit. 
Control passes back to the user task only in the case of a 
directive error. 
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USER 




EXECUTIVE 



TRAP 
VECTOR 



DIRECTIVE 
DISPATCHER 
(DRDSP) 



DIRECTIVE 
ROUTINES 




Figure 2-1 Directive Implementation 



Functions Available Through Executive Directives 

Table 2-1 lists many of the Executive directives which are 
available on your system. For a complete list of the directives 
in each group, see section 5.1 on Directive Categories, in the 
RSX-11M/M-PLUS Executive Reference Manual. 



Many of the functions available are discussed more fully in 
this module, and in the modules on Using the QIO Directive, Using 
Directives for Intertask Communication, and Dynamic Regions. No 
attempt is made to discuss every executive directive. You should, 
however, at the end of this course, know enough to be able to look 
up any directive in the manual and invoke it. 

Each directive is documented individually in Chapter 5 of the 
RSX-11M/M-PLUS Executive Reference Manual . The directives appear 
there in alphabetical order by MACRO-11 name. 
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Table 2-1 Types of Directives 



Type 




Descr iption 


Task Execution 
Control 


ABRT$ 
EXIT$S 
RQb 1 ■? 
RSUM$ 
RUN$ 

STOP$ 
USTP$ 


Abort task 
Exit task 

RpniiP«;f f-fl^k 
r\ cz u c o u uo j\ 

Resume task 

QnQnpnrl 1~ ^ ^ k 

Stop task 
Unstop task 


Task Status 
Control 


ALTP$ 

DSCP$S 

ENCP$S 


Alter priority 
Disable checkpointing 
Enable checkpointing 


Informational 


GPRT$ 


Get partition parameters 
Get time parameters 


Event- 
Associated 


CLEF$ 
CRGF$ 

£i Lilj r v 

MRKT$ 
RDAF$ 
RDXF$ 
SETF$ 
WTSE$ 


Clear event flag 
Create group global flags 
Eliminate group global flag 
Mark time 

Read all event flags 
Read extended event flags 
Set event flag 
Wait for single event flag 


i r ap~"ASSOC laucll 


ASTX$S 

SREA$ 

SVTK$ 


AST Exit 

Specify requested exit AST 
Specify task SST vectors 


I/O and 

Intertask 

Communications 


ALUN$ 

QIO$ 

QIOW$ 


Assign LUN 

Queue I/O request 

Queue I/O request and wait 




RCVD$ 
SDAT$ 


Receive data 
Send data 


Memory 
Management 


CRRG$ 
MAP$ 


Create region 

Map address window 


Parent/ 
Offspring 
Taski ng 


EXST$ 
SPWN$ 


Exit with status 
Spawn task 
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The Directive Parameter Block (DPB) 

The Directive Parameter Block is set up as the first step in 
invoking an Executive directive. It contains all the information 
the Executive needs to perform the requested service. This 
includes a Directive Identification Code (DIC) which identifies 
the Executive directive being requested. See Figure 2-2 for a 
picture of the Directive Parameter Block layout. 

The length of the DPB is included because its length varies 

depending on which directive is being invoked. The rest of the 

DPB is built from the arguments specific to the particular 
directive . 



# OF WORDS 
IN DPB = M + 1 



DIRECTIVE 

IDENTIFICATION 

CODE 



WORD 1 



WORD 2 



WORD 3 




FROM DIRECTIVE 
ARGUMENTS 



WORD M-1 



WORD M 



TK-7512 



Figure 2-2 The Directive Parameter Block 
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Macros are provided in the system macro library 
[ LB : [1,1] RSXMAC . SML] to set up the DPB and invoke each executive 
directive. The format of the macro call is as follows. 



xxxx$x argl , arg2,arg3, . . . , argn 



Example : 

GLUN$C 4, BUFF 



The macro name determines the DIC and the length of the DPB; 
the arguments in the macro call are used to build the rest of the 
DPB. The DPB for the example given is as shown below. 



BUFF 



For additional information on the macros for each directive, 
see the individual directives in Chapter 5 of the 
RSX-11M/M-PLUS Executive Reference Manual . 

The Executive preserves (saves and restores) all task 
registers when a task issues a directive. 



The Directive Status Word (DSW) 

Upon completion of directive processing, the Executive 
returns a code in the Directive Status Word which gives the status 
of the request. The DSW is located in the task header at location 
$DSW, a global symbol which can be used to reference the value 
directly. Successful completion is usually indicated by a DSW 
value of +1 (IS. SUC) . 

A negative value indicates an error. Different negative 
values correspond to different sources of errors. These values 
and their general meanings appear in Appendix B of the 
RSX-11M/M-PLUS Executive Reference Manual and in the RSX-11M 
Mini Reference Manual . In addition, specific error values and any 
special meanings are documented with each individual Executive 
directive call in Chapter 5 of the RSX-11M/M-PLUS Executive 
Reference Manual. 
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In addition to setting the DSW, the Executive clears the 
carry bit to indicate successful directive execution and sets the 
carry bit to indicate failure. You can check for errors using a 
BCC or BCS instruction immediately after the directive call. In 
that case, access the actual DSW value only if you need it. 



Sample Program 

Example 2-1 illustrates the use of the Request Task and the 
Exit Task directives. The directives are given below, along with 
a description of their functionality. 

The Exit Task Directive 

Format: EXIT$S (no arguments) 

Used to make a task inactive and to free up the system 
resources it uses. 

The Request Task Directive 

Format: RQST$ tsk 

where tsk is the name of the task to be requested 
RQST$C TASKA 

Used to request the specified installed task 

Offers the same functionality as the DCL RUN (immediately) 
command for an installed task. 

Before using any directive in a program, always read over the 
description of that directive in Chapter 5 of the RSX-11M/M-PLUS 
Executive Reference Manual . Specifically, pay attention to the 
different directive parameters and their meanings. See section 
5.3 (on System Directive Descriptions) for an explanation of the 
organization of the directive desciptions and what elements are 
included . 

Each program example in this course contains the following: 

• Source code, with line numbers added 

• A sample run session 

• Bulleted items which are described in the text. 
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See the Student Guide for additional information about how to 
use the program examples. 

The following comments are keyed to the example. 

O Tne macros for invoking directives must be specified to 
the assembler in a .MCALL statement. 

Q A number of special macros have been supplied with this 
course to assist you in class. Since you don't yet know 
how to issue the QIO directive, which is covered in the 
next module, the TYPE macro is supplied to perform writes 
to TI:. 

Example : 

TYPE <HELLO THERE> 

issues a QIO directive to display the text 
"HELLO THERE" at your terminal. 

The use of the supplied macros is documented in Appendix 
A, along with the source code for all macros and any 
internal subroutines they call. 

Q Invoke the Request Task directive. The task name must be 
the installed name (...PIP), not just PIP. 

Q The carry bit is set by the Executive in the case of an 
error and is cleared in the case of success. Always check 
the status on return from an executive directive. 

O Tne only case in which control will return to the user 
task after an EXIT$S call is if a directive error occurs. 
This is very unlikely to happen. 

Q This is an easy way to display the DSW value. The IOT 
instruction causes the Executive to abort the task and 
display all registers at TI : . 

O ON THE RUN SESSION. A run session is included for each 
example program. 

The simple method for displaying directive error messages is 
used here to keep things simple. This technique may be useful in 
the early stages of debugging a program. Later, this code should 
be replaced with code which displays more readable error messages. 
Techniques for doing this are covered in the next module. 
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1 ♦TITLE REQUES 

2 ♦ I DENT /Ol/ 

3 +ENABL LC ? Enable lower case 

4 yf 

5 y FILE REQUES ♦ MAC 

6 » 

7 y This task displays a message y then reauests PIP* and 

8 y exits 

9 ? 

10 y Assemble and task-build instructions y to include 

11 J supplied macros and subroutines* 

12 y 

13 y MACRO/LIST LB * L" 1 y 1 .1 PROGM ACS/LI BR AR Y ydev J Cufd."] REQUES 

14 y LINK/MAP REQUES y PROGSUBS/LIBRARY 

15 y» 

16 «MCALL EXIT$SyRQST$C y External system macros 

17 y + 

18 y TYPE is a macro supplied in the macro library 

19 9 LB * II' 1 y 1 3PR0GMACS ♦ MLB for doing I/O. It issues QIC) 

20 y directives for you* TYPE calls subroutines in the 

21 y object library LB* CI y 1 3PRQGSUBS*0LB* 

22 y- 

23 *MCALL TYPE y External supplied macro 

24 y 

25 y Display startup text 

26 START? TYPE <REQUES HAS STARTED AND WILL REQUEST PIP> 

27 y Display message 

28 y Reauest PIP 

29 RQST$C ♦♦♦PIP y Reauest PIP 

30 BCS ERR y Branch on directive 

31 y error 

32 EXIT*S ? Exit 

33 y Error code 

34 ERR ♦ MOV *DSW*R0 y Move DSW for display 

35 .TOT y Trap and display 

36 y registers 

37 *EHl\ START 



Run Session 
>RUN REQUES 

REQUES HAS STARTED AND WILL REQUEST PIP 
PIP>~Z 



Example 2-1 Requesting a Task 
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DIFFERENT FORMS OF THE DIRECTIVE CALLS 

There are three different forms for each directive call, 
which correspond to three different methods for setting up the DPB 
and invoking the directive. For each directive call in a program, 
you may select which form to use. 

With two forms, the $ and the $C , the DPB is set up in a data 
area of your task at assembly time. In the $ form, you use one 
system macro to set up the DPB, and another system macro at run 
time to invoke the directive. In the $C form, you use just one 
macro to both set up the DPB and invoke the directive. The 
assembler separates the DPB setup into a data area for you. In 
the $S form, the DPB is set up on the user stack at run time and 
the directive is invoked immediately afterwards. As in the $C 
form, only one system macro is needed to both set up the DPB and 
invoke the directive. 

Decide which form of each directive call to use based on the 
following . 

• Task size 

• Run time efficiency 

• Programming ease 

• Knowledge of directive parameters, whether known at 
assembly time or at run time 

• Requirements for reentrant code (e.g., if the code is 
contained in a shareable library) . 

Each of the three forms is further described below, using the 
Set Event Flag directive (SETF$) as an example. 

The $ Form 

Figure 2-3 shows the $ form, so named because the last 
character in the macro name is '$* (e.g., RQST$, ABRT$ , etc.). In 
the source code, use a system macro to set up the DPB in a data 
area, specifying a label to identify it. In the example, LABEL is 
the label for the DPB set up by the macro SETF$. The DPB is set 
up at assembly time. The first word of the DPB contains the DPB 
length in the high-order byte and the DIC in the low-order byte. 
The next word contains the event flag number argument. Any 
additional arguments would appear in successive words. 
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TASK IMAGE 



SOURCE 

LABEL: SETF$ 52. 

START: • 

DIR$ #LABEL 



EXPANDS TO 



LABEL: .BYTE 33..2 
.WORD 52. 



START: 



MOV #LABE 
EMT 377 



L,-(SP)j^ 



DPB IN DATA AREA: 



2. 


33. 


52. 



HEADER 

"stack 
task code 



XXXXXXX 
XXXXXXX 



XXXXXXX 
XXXXXXX 



Figure 2-3 The * $' Form 



• Use the $ form of the directive macro to set up the DPB in 
the data area at assembly time. 

• Use DIR$ macro to initiate the directive at run time. 

• The DIR$ macro pushes the DPB starting address onto the 
stack, then traps to the Executive. 

• Arguments in the $ form must be valid for .BYTE, .WORD, or 
. RAD50 assembler directives. 

valid arguments: 14.^, 204 ,TASKA, BUFF 

invalid arguments: #14. ,#204 , #TASKA,@BUFF,R2 



H Throughout this course, a decimal point following a numeral 
indicates that it is in base 10 notation. If no decimal point 
follows a numeral, it is usually in base 8 notation. The 
exception is when base 10 is clear from the context; e.g., 16 
bits . 
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Use the separate system macro DIR$ at run time to invoke the 
directive, specifying the label of the DPB. This macro pushes the 
starting address of the DPB onto the stack and then traps to the 
Executive. The label LABEL, which corresponds to the starting 
address of the DPB, is specified in the DIR$ call. If other 
directives are invoked in the same task, DIR$ is used each time, 
with the appropriate address (or label) specified. 

Arguments in the $ form of the directive must be valid 
arguments for .BYTE, .WORD, or . RAD50 Assembler directives. This 
is necessary because the macros contain .BYTE, .WORD, or .RAD50 
assembler directives. See the examples that accompany Figure 2-3. 

This form of the directive is run time efficient. In 
addition, if the same directive is used later in the program to 
clear another event flag (e.g., 53.) it is possible to use the 
same DPB for both calls. Offsets within the DPB are defined by 
global symbols. Hence, at run time, the instructions INC 
LABEL+C . LEEF or MOV # 53 . , LABEL+C . LEEF would change the existing 
DPB for reuse, using another DIR$ #LABEL call. This saves on task 
space, especially for directives with many arguments. 

One drawback of this method is that it is harder to use 
because two separate macros are needed for each directive 
invocation. Another is that it is not reentrant if the DPB is 
changed at run time. For example, reentrant code is required in 
shareable subroutines. 
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The $C Form 

Figure 2-4 shows the $C form, so named because the last 
characters in the macro name are '$C* (e.g., RQST$C, ABRT$C, 
etc.). This form functions similarly to the $ form, but it is 
easier to use because the DPB setup and actual directive 
invocation are combined into one macro call. The assembler 
separates the DPB setup into a data area in a separate Psect named 
$DPB$$. At run time, a pointer to the DPB is pushed onto the 
stack when the directive is invoked, as in the $ form. 

Arguments for the $C form must also be valid arguments for 
.BYTE, .WORD, or .RAD50 assembler directives. Also, there is an 
additional optional argument for all $C form calls which is only 
necessary if a call is made from a Psect other than the default 
blank Psect. This argument specifies the Psect from which the 
call is made. This allows return to this Psect for the directive 
invocation and other code. In Figure 2-3, the Psect PROGS 
contains the main code. 

An advantage of this method is that it is easier to use than 
the $ form and is just as efficient at run time. One restriction 
is that a given DPB cannot be accessed and modified at run time. 
Therefore, to clear event flag 53., a separate CLEF$C 53. 
directive is required, which generates a separate DPB. So for 
repeated use of a directive, the $C form requires more task space. 
Another restriction, due to the inaccessibility of the DPB at run 
time, is that all directive arguments must be known at assembly 
time. One other advantage of the $C from is that it is always 
reentrant, since the DPB cannot be changed. 
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TASK IMAGE 



SOURCE 

.PSECT PROGS 
START: I 

SETF$C 52. f PROGS 



EXPANDS TO 



.PSECT PROGS 



START: 



f .PSECT $DPB$$' 
$$$ = . 

.BYTE 33., 2 

.WORD 52. 

.PSECT PROGS 

MOV #$$$, - (SP) 

L EMT 377 



DPB IN DATA AREA: 



2. 


33. 


52. 



HEADER 
_ STACK 

TASK CODE 

PSECT PROGS 

XXXXXXX 
XXXXXXX 

PSECT $DPB$$ 

XXXXXXX 
XXXXXXX 



Figure 2-4 The $C Form 



Using the $C Form: 

• Needs only one macro call. 

• Sets up the DPB in the data area at assembly time. 

• The $C form, as in the $ form, also pushes the DPB address 
onto the stack and traps to the Executive at run time. 

• Optional argument specifies the current Psect if other 
than the blank Psect. 

• Arguments must also be valid for .BYTE, .WORD, or .RAD50 
assembler directives. 
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The $S Form 

Figure 2-5 shows the $S form, so named because the last 
characters in the macro name are ■ $S' (e.g., RQST$S, ABRT$S, 
etc.). In this form, the DPB setup and the directive invocation 
itself are combined into one macro call, as in the $C form. 

However, unlike either the $ or the $C form, in the $S form, 
the DPB is built at run time instead of at assembly time, and it 
is built on the stack instead of in the task's data area. This 
means that all arguments must be valid source arguments for MOV or 
MOVB instructions. See the examples with Figure 2-5. 

One advantage of this method is that the same call can be 
used with different arguments, since a new DPB is built with each 
executive directive macro call. Therefore, you can place 
parameters which aren't known until run time in registers or data 
areas. You can then specify the registers or the addresses of the 
data values as arguments in the directive call. 

Another major advantage is that the code can be reentrant 
even if the directive arguments are modified. For example, a 
register may be used as an argument. Because each task has its 
own registers, each task has its own independent copy of the 
argument . 

The major disadvantage of this form is that it executes the 
slowest of the three forms, because every word of the DPB must be 
pushed onto the stack immediately before invoking the directive. 
The more arguments the directive has, the longer it takes. 

If a directive has no arguments (e.g., EXIT$) , it is just as 
run-time efficient to use the $S form, because the complete DPB is 
only one word long. Therefore, it takes one instruction to push 
the complete DPB onto the stack in the $S form. It also takes one 
instruction to push the address of the DPB onto the stack in the $ 
and $C forms. Any directive which has no arguments (e.g., Exit 
Task, Suspend Task) is available with only the $S form. 
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TASK IMAGE 



SOURCE 



EXPANDS TO 



START: 



START: 



SETF$S #52. 



MOV 
MOV 
.BYTE 
EMT 



#52.-(SP) 
(PC)+-(SP) 
33.,2 
377 



HEADER 



STACK 



TASK CODE 



XXXXXXX 
XXXXXXX 
XXXXXXX 
XXXXXXX 



DPB ON STACK 
(AT RUN TIME): 



2. 


33. 


52. 



TK-7732 

Figure 2-5 The $S Form 



Using the $S Form: 



• Needs only one macro call. 



• The $S form pushes complete DPB onto the stack at run 
time, then traps to the Executive. 

• Arguments must be valid source arguments for MOV 
instructions . 

valid arguments: #15 . ,#204 , #BUFF,R1 

possible misused arguments: 15., 204, BUFF 

Use 15., 204 or BUFF only if you want the contents of 

those locations for the directive parameters. 
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One other disadvantage of using the $S form arises when task 
or partition names are specified as arguments. These arguments 
must be in Radix-50 format in the DPB. If the $C or $ form is 
used, the macro converts the ASCII name specified as an argument 
to Radix-50 format. If the $S form is used, you must place the 
name in a data area in Radix-50 format, then specify the address 
of the data in the macro call. You can either use a .RAD50 
assembler directive at assembly time or the $CAT5 subroutine. See 
Appendix A of the IAS/RSX MACRO- 11 Reference Manual for a 
description of the Radix-50 character set. Also, see 6.3.6 9 (on 
the . RAD50 assembler directive) in the same manual for a 
discussion of Radix-50 format. 



Examples 

Examples 2-2, 2-3, and 2-4 illustrate the use of the three 
forms of the directive calls. All three forms send a 13(10) = 13. 
word packet of data to a task RECEIV. The source code for RECEIV 
follows the code for Example 2-3. Don't worry yet about the 
actual mechanics of how to set up sender tasks and receiver tasks. 
These are discussed in the module on Intertask Communication. 
Just compare the uses of the different forms of directives. The 
following notes are keyed to all three examples. 

O The .MCALL statement declares the particular macro 
directive call or calls to be used, including the form. 

Q Data area setup requirements: 

$ form: SDAT$ directive sets up the DPB in the data 
area . 

$C form: Nothing is set up separately. The Assembler 
sets up the DPB in a data area for you. 

$S form: Normally, nothing is set up in a data area. 

Task names are an exception, since they must 
already be in Radix-50 format. Therefore, 
the task name is set up in Radix-50 format 
in the data area. The argument in the $S 
call is the address of the task name. 
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O Executing the directive call. 

$ form: Use the separate DIR$ macro. 

$C form: Use the single SDAT$ call. The DPB is set 
up at assembly time by this macro. Just the 
directive invocation is performed at run 
time . 

$S form: Use the SDAT$S call. The entire DPB is 
pushed onto the stack at run time and then 
the directive is invoked. 

O ON THE RUN SESSION. First run the sender. Then run the 
receiver to receive and display the data. 

Note the difference in the form of the arguments in the $S 
form. These arguments are source arguments for MOV or MOVB 
instructions. For the $ and $C forms, the arguments are arguments 
for .WORD, .BYTE, or . RAD50 Assembler directives. 



6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 



♦ TITLE SEND 

♦ I DENT /01/ 
♦ ENABL LC 



9 Enable lower case 



FILE SEND ♦MAC 



This task sends 3 buffer of 13* words of data to the 
task RECEIV for processing* It sets common event flas 
33* when the data is Queued for RECEIV 

It uses the $ form of the Send Data directive 

Assemble and task-build instructions* 

MACRO/LIST LB* C 1 » 1 3PR0GMACS/LIBRARY , dev : Cuf dUSEND 
LINK/MAP SEND v LB * C 1 v 1 3PR0GSUBS/L I BRARY 

Install and run instructions* 

This task does not have to be installed* RECEIV 
must be installed* 

♦MCALL SDAT$yEXIT*S? DIR* ? System macros 
♦MCALL TYPE f Supplied macro 



buffer: ♦word 



ly2»3y4j-5M6?7y8*y9*yl0*>llwl2«>13» 
$ Data to send 



Example 2-2 Using the $ Form of the Directives (Sheet 1 of 2) 
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29 
O 30 

31 
32 
Q 33 

34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 



t Create DPB separately in a data area for the * form 



SEND t 



ERR* 



SDAT* 



START* MR* 

BCS 
TYPE 



EX.TT$S 
MOV 
I0T 
♦ END 



RECEIVy BUFFER y33» r Set up DPB for 



? directive 



♦SEND 



t Issue directive to 
y send data to RECEIV 
ERR ? Branch on dir error 

<DATA QUEUED TO RECEIV> i Display 
? success message 



♦DSWf Rl 



START 



v Exit 

9 Move DSW to Rl for 
9 display 

} Trap and display 
9 registers 



Run Session 



>INS RECEIV 
>RUN SEND 

DATA QUEUED TO RECEIV 
>RUN RECEIV 

12 3 4 



10 



11 



12 



13 



3 
4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 



♦ TITLE RECEIV 

♦ I DENT /01/ 
♦ ENABL LC 



? File RECEIV ♦ MAC 



This task 
SENDS 3nd 



receives 
displays 



the data 
it at TI; 



9 Enable lower case 



sent by SEND > SENDCy or 



RBUFF 

buff: 
fmt: 



start: 



9 Edit 



? trror 
ERR1 : 



♦MCALL 
♦ MCALL 

♦ BLKW 

♦ BLKB 
♦ASCII 
♦ASCIZ 

RCVD*C 
BCS 
binary 
MOM 
MOV 
MOV 

CALL 
TYPE 
EXIT*S 
code 
MOV 
I OT 

♦ END 



RCVD*Cf EXIT*S 

TYPE 

15* y Buffer for data received 

80* 9 Buffer for output message 

/%3S%D%4S%D%4S%D%4S%D%4S%D/£4S%D%4S%D/ 
/%4S%D%4S%D%4S%D%4S%D%4S%D%4S%D/ 



9 RBUFF 
ERR1 
data into ASCI 
#BUFF»R0 
#FMTs»Rl 
#RBUFF+4?R2 

*EDMSG 
#BUFF jRI 



*DSW*R0 



9 Receive from anyone 

9 Bra n c h on d i r e c t i v e e r r o r 
message for display 

9 Addr of output buffer 

9 Addr of format string 

9 Addr of data received? 
9 skip sender task name 

y Edit ouput message 

5 Display output message 

y Exit 

y Move DSW for display 

y Trap and display 
9 registers 



START 



Example 2-2 Using the $ Form of the Directives (Sheet 2 of 
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1 


♦ TITLE 


SENDC 


2 


♦I DENT 


/01/ 


3 


♦ENABL 

* j. 


LC 9 Enable lower case 


4 

5 


i FILE SENDC* MAC 


6 
7 


r This task sends 3 buffer of 13* words of data to the 


8 


? t3sk RECEIV 


for processing* It sets common event flag 


9 


i 33* when the 


data is ctueued for RECEIV 


10 






11 
12 


y It uses the 


$C form of the Send Data directive 


.1.3 


9 Assemble and 


task-bui 1 d instructions: 


14 






15 


f MACRO/LIST LB* CI 9 1 3PR0GMACS/LIBRARY y dev : Cuf dUSENDC 


16 






17 


9 LINK/MAP SENDC y LB : C 1 y 1 3PR0GSUBS/LIBRARY 


18 






19 


9 Install snd 


run instructions: 


20 






21 


9 This task does not hsve to be installed* RECEIV 


22 


9 must be installed* 


23 






24 


♦MCALL 


SDAT$CyEXIT$SyDIR$ ? System macros 


25 


♦ MCALL 


TYPE t Supplied macro 


26 






27 






28 


buffer: *word 


Iy2y3y4y5y6y7y8* y9* ylO* yll* yl2* yl3* 


29 




y Data to send 


30 


start: sdat$c 


RECEIVyBUFFERy33* y Issue directive to 


31 




y send data to RECEIV 


32 


BCS 


ERR y Branch on dir error 


33 


TYPE 


<DATA QUEUED TO RECEIV> ? Display 


34 




y success message 


35 


EXIT$S 


y Exit 


36 






37 


ERR : MOV 


♦DSWfRl i Move DSW to Rl 


38 


IOT 


y Trap and display 


39 




y registers 


40 


♦ END 


START 



Run Session 

>INS RECEIV 
>RUN SENDC 

DATA QUEUED TO RECEIV 
>RUN RECEIV 

1 2 3 4 5 6 7 8 9 10 11 12 13 



Example 2-3 Using the $C Form of the Directives 
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1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 

O 23 

24 
25 
26 
27 
28 
29 
^ 30 
O 31 

O 33 

34 
35 
36 
37 
38 
39 
40 
41 
42 
43 



♦TITLE SENDS 
♦ I DENT /01/ 
♦ENABL LC 



i Enable lower case 



i + 

? FILE SENDS* MAC 
f 

i This task sends a buffer of 13* words of data to the 
r task RECEIV for processing* It sets common event flag 
i 33* when the data is Queued for RECEIV 

r 

v It uses the $S form of the Send Data directive 
y 

9 Assemble and task-build instructions* 
r 

> MACRO/LIST LB* CI ? lUPROGMACS/LIBRARYrdevi Cuf dUSENDS 

f LINK/MAP SENDS » LB* C 1 > 1 3PR0GSUBS/LIBRARY 

? 

» Install and run instructions* 
J 

? This task does not have to be installed* RECEIV 

t must be installed 

y — 

♦MCALL SDAT$SyEXIT*S»DIR* 5 System macros 
♦MCALL TYPE > Supplied macro 



buffer: ♦word 



I?2?3y4*5*6>7»8*>9**10*>ll*rl2*»13* 
r Data to send 



r Task names must be specified in Radix-50 format for 

r the $S form 

TASKNM* *RAD50 /RECEIV/ 

r 

STARTi SDAT*S *TASKNM 9 *BUFFER 9 #33 ♦ r Issue directive to 

f send data to RECEIV 
BCS ERR f Branch on dir error 

TYPE <DATA QUEUED TO RECEIV> i Display 

r success message 
f Exit 



err: 



EXIT*S 

MOV 
IOT 

♦ END 



♦DSWfRl 

START 



r Move DSW to Rl 
r Trap and display 
9 registers 



Run Session 



>INS RECEIV 
>RUN SENDS 

DATA QUEUED TO RECEIV 
>RUN RECEIV 

1. 2 3 4 



10 



11 



12 



13 



Example 2-4 Using the $S Form of the Directives 
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Repeated Use of a Directive with Different Arguments 

The following sections of code illustrate the use of the 
different directive forms when using a directive several times in 
a program. All three clear event flags 5. to 15. , using the 
Clear Event Flag directive 11 times. Note in particular that the 
$ form uses the same DPB over and over again. The $C form macro 
calls result in 11 different DPBs in the data area of the task. 
The $S form uses a register as an argument and a new DPB is 
generated for each call; but on the stack, not in a data area. 



Use the Executive directive first for event flag 5, then 
access and change the DPB for the other ten calls. In the example 
below, the DPB begins at CLEAR. 



NOTE 

A discussion of event flags and their uses 
appears later in this module. 



$ Form 



. MCALL CLEF$, DIR$ 



CLEAR: 



CLEF$ 5. 



START: 



AGAIN: 



MOV 

DIR$ 

BCS 

INC 

CMP 

BGT 

INC 

BR 



#5. ,R0 

#CLEAR 

ERR 

R0 

R0,#15. 

DONE 

C LEAR+C . LEEF 
AGAIN 



DONE: 
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$C Form 

The $C form cannot access the DPB; so make 11 different 
calls with separate DPBs . 

. MCALL CLEF$C 

START: 





c 

D • 




PRD 




f. 

O • 


DP C 
DUO 


Ci r\r\ 


CLEF$C 


7. 


BCS 


ERR 


CLEF$C 


8. 


BCS 


ERR 


CLEF$C 


9. 


BCS 


ERR 


CLEF$C 


10. 


BCS 


ERR 


CLEF$C 


11. 


BCS 


ERR 


CLEF$C 


12. 


BCS 


ERR 


CLEF$C 


13. 


BCS 


ERR 


CLEF$C 


14. 


BCS 


ERR 


CLEF$C 


15. 


BCS 

• 
• 
• 


ERR 
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$S Form 

A new DPB is pushed onto the stack for each call. Use a 
register value for an argument. Make the same call 11 times; 
update the register each time. 



START: 



. MCALL CLEF$S 



MOV #5,R0 

AGAIN: CLEF$S R0 

BCS ERR 

INC R0 

CMP R0,#15. 

BLE AGAIN 



Table 2-2 gives a summary of the three forms of the directive 

call . 
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Table 2-2 Summary of the Directive Forms 



DPB Location 



$ Form 

Data area 
of current 
Psect 



DPB Creation At assembly 
time 



Advantages 



DPB reusable, 
easily changed 



Run time 
efficient 



Disadvantages Not reentrant 
if DPB changed 

Need two 
macro calls 



Recommended 
Use 



No tes 



If parameters 
not set at 
assembly time 
and run time 
ef f i c i ency 
critical 



For repeated 
use with same 
arguments 

Arguments 
valid in 
.WORD or 
.BYTE 



$C Form 

Data area 
of Psect 
$DPB$$ 

At assembly 
time 

Easily coded 



Run time 
efficient 

Reentrant 

DPB can't be 
changed 

Uses more space 
for multiple 
calls 

Known direc- 
tives used once 

Parameters all 
set at assembly 
time and dir- 
ective used 
once 



Return Psect 
may be needed 
in call 

Arguments valid 
in .WORD or 
.BYTE 



$S Form 

On task stack 

At run time 



Arguments can 
be changed at 
run time 

Can be reentrant 
even if DPB 
changed 

Run time 
inefficient if 
directive has 
many arguments 



If directive has 
no arguments 

When parameters 
not set at 
assembly time 
and run time 
efficiency not 
critical or code 
must be reentrant 



Arguments 
valid for 
MOV or MOVB 
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ADDITIONAL DIRECTIVE CONSIDERATIONS 



An Alternative Method for Error Checking 

An additional argument can be used to specify the address of 
an error subroutine. 

Fo rmat : 

$ Form $C Form 

DCLEF: CLEF$ 53.- 

DIR$ #DCLEF, ERROR CLEF$C 53.,, ERROR 

$S Form 



CLEF$S #53., ERROR 



NOTES 

The extra null argument in the $C form is for 
the optional Psect. 

In the $S form, no •#* is needed on the 
address, since this becomes a JSR PC, ERROR. 
This argument is not moved to the stack. 



In all three cases, the extra argument causes the following code 
to be generated: 



;macro without error address 



;additional code 
BCC .+6 
JSR PC, ERROR 
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This results in a branch to the instruction following the 
directive macro if the directive is executed successfully, and a 
call to the subroutine ERROR if not. It is equivalent to 
including the following code yourself. 

DIR$ # LABEL 

BCC OK 

JSR PC, ERROR 

OK: 



Note that in case of an error the transfer to the error 
routine is with a JSR, not a JMP or BR. The result is that the 
return address is pushed onto the stack. If you generate an error 
message and exit, the JSR won't cause any problems because the 
stack isn't accessed. 

If, on the other hand, you attempt to recover from the error, 
you must remember that the return point is on the stack. You must 
either use a RETURN (RTS PC) or clear the return address off the 
stack if you wish to branch to a different location. 



Examples Using Other Directives 

The following directives are used in Example 2-5. 

• Suspend Task (SPND$S) 

Used to suspend itself 

Can be resumed by another task issuing a Resume task 
directive or by an operator using the DCL CONTINUE 
command 

• Alter Priority (ALTP$) 

Alters the running priority of an active task 

• Disable Checkpointing (DSCP$S) 

Disables checkpointing for a checkpointable task 
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• Enable Checkpointing (ENCP$S) 

Enables checkpointing again after a DSCP$ directive 

• Extend Task (EXTK$) 

Modifies the size of the task by a positive or 
negative number of 32-word blocks. 

The $S form of SPND$, DSCP$, and ENCP$ is recommended because 
each directive has no arguments. 

Example 2-5 shows the use of a variety of directives. See 
the run demonstration below the source code. The following 
comments are keyed to the example. 

Rl is a directive counter. When several directives are 
used in a program, the counter helps keep track of which 
directive caused an error. After an IOT r n in Rl means 
that there was an error on the nth directive. R0 contains 
the DSW value. 

Task suspends itself. This allows the operator to use the 
DCL SHOW TASKS/ACTIVE command to examine the task 
parameters. 

The task is loaded at physical address 00615200(8) to 
00617200(8). SPN means the task is suspended. 

The operator must use the DCL CONTINUE command to resume 
the task. 

O Suspend again after you disable checkpointing and alter 
the running priority. 

Note the change in running priority (PRI) . CKD indicates 
the disabling of checkpointing. 

Q Suspend again after you enable checkpointing, alter the 
priority back to 50. , and extend the task. 
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Note the change in priority. Note also that the task was 
checkpointed and is now loaded at addresses 01045200(8) to 
01067200(8). The new task size is 22000(8) bytes, 
compared to 2000(8) bytes before, as shown below. The 
extend is for 200(8) blocks, where each block is 100(8) 
bytes long, which means there are 20000(8) extra bytes. 
See Appendix B for a conversion table of bytes to blocks 
and of octal to decimal. 

Before : 

00617200 (8) 
-00615200 (8) 



2000(8) bytes 

After : 

01067200 (8) 
-01045200 (8) 



22000 (8) 
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1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
L41 
42 
r 43 
44 
45 
46 
47 



♦ TITLE MISC 
♦ I DENT /01/ 
♦ ENABL LC 



? Enable lower case 



FILE MISC*MAC 



This task uses some miscellaneous Executive directives 
to suspend itself* alter its running priority* disable 
and enable checkpointing y and extend its task size* 

Task-build instructions* 

LINK/CHECKPOINT/MAP MISC 

since the task must be checkpointable to allow 
disabling of checkpointing and extending its size 

Install and Run instructions* 

Install the task* Then Run it to start it up* 

The task will suspend itself several different 

times* Each time* use the command 

SHOW TASKStMISC/ACTIVE/FULL (MCR ATL MISC) 

to examine the changes* Use the command 

CONTINUE MISC (MCR RESUME MISC) 

to resume the task* 



START ♦ 



Make 



ok: 



good: 

J Make 



Example 2-5 



♦MCALL 


SPND*S * ALTP*C * DSCP*S y ENCP*S 


♦MCALL 


EXTK*C>EXIT*S 


CLR 


Rl 


y Directive counter for errors 


SPND*S 




* Suspend to allow status check 


BCS 


ERR1 


r Branch on directive error 


some changes and 


then suspend again 


DSCP*S 




5 Disable checkpointing 


BCC 


OK 


r Branch on good directive 


JMP 


ERR2 


* Jump to error code 


ALTP*C 


ylO* 


y Alter running priority 


BCC 


GOOD 


i Branch on good directive 


JSR 


PC*ERR3 


f Call error subroutine 


SPND$S 


ERR 4 


y Suspend to allow status check 


some other changes and then suspend again 


ENCP*S 




y Enable checkpointing again 


BCS 


ERRS 


y Branch on directive error 


ALTP*C 


y y y ERR6 


y Return priority to original 


EXTK*C 


200 


y Extend task size by 200(8) 






y blocks 


Us ing 


Several 


Directives (Sheet 1 of 2) 
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48 




BCC 


ALSOOK 


7 A. 1 1 C) 1 1 L 1 1 wl 1 .Zfc U w '.J <mIJ.IC71mwJ.VC7 


49 




CALL 


ERR 7 


i O&l 1 prrnr ^nhpoii+infa 

7 w w .1. 4* Vv7 1 1 W 1 S> L. 1 1 K.I >.J 1/ J> 1 1 W 


50 


ALSOOK'i 


SPND*S 




5 Sii*^PP*i"iri aci^iri 


51 




BCC 


AGNOK 


5 Branch on rli r^rti ok 


52 




BR 


ERRS 


f Branch on directive error 


53 


agnok: 


EXIT$S 




9 Exit 


54 


5 Error 


handling 




55 


ERRS* 


INC 


Rl 


? 8 means error on 3rd SPND$S 


56 


ERR7J 


INC 


Rl 


f 7 means error on EXTK*C 


57 


ERR6J 


INC 


Rl 


5 6 means error on 2nd ALTP$C 


58 


ERRS * 


INC 


Rl 


9 5 means error on ENCP$S 


59 


ERR4* 


INC 


Rl 


9 4 means error on 2nd SPND$S 


60 


ERR3 : 


INC 


Rl 


9 3 means error on 1st ALTP$C 


6.1 


ERR 2* 


INC 


Rl 


9 2 means error on DSCP$S 


62 


ERR1 : 


INC 


Rl 


9 1 means error on 1st SPND$S 


63 




MOM 


$dsw?ro 


9 Move DSW for display 


64 




IOT 




9 Trap and display registers 


65 




♦ END 


START 





Run Session 

>INS MISC 
>RUN MISC 

>sh0w tasks/ active full misc 

misc 055420 gen 054500 00615200-00617200 pri - 50* dpri - 50* 
status: spn »pmd 

ti - tt11j ioc - 0* bio - 0. eflg - 000000 000000 ps - 170000 

PC -- 001264 REGS 0-6 000000 000000 011300 140130 000000 000000 001254 
>C0NTINUE MISC 
>SH0W TASKS/ ACTIVE FULL MISC 

MISC 055420 GEN 054500 00615200-00617200 PRI - 10. DPRI ~ 50* 
STATUS J CKD SPN -PMD 

TI • TTli: IOC - 0* BIO - 0* EFLG - 000000 000000 PS - 170000 
PC - 001324 REGS 0-6 000000 000000 011300 140130 000000 000000 001254 
.'-•CONTINUE MISC 

>SH0W TASKS/ ACTIVE FULL MISC 

MISC 055420 GEN 054500 01045200-01067200 PRI - 50* DPRI - 50. 
STATUS* SPN -PMD 

TI - TTli: IOC - 0* BIO - 0* EFLG - 000000 000000 PS - 170000 
PC - 001400 REGS 0-6 000000 000000 011300 140130 000000 000000 001254 
.^•CONTINUE MISC 

>SH0W TASKS/ACTIVE FULL MISC 
ATL - Task not active 

Example 2-5 Using Several Directives (Sheet 2 of 2) 
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This example illustrates a number of techniques for directive 

error checking. At lines 33 and 44, a BCS is used. At lines 36, 

39, 48, and 51, a BCC is used to branch past the transfer to the 
error handling code. 

The transfers themselves also differ. At line 37, a JMP is 
used. At line 40, a JSR PC is used, while at line 49, a CALL 
which is equivalent to a JSR PC is used. At line 52, a BR is 
used. Finally, at lines 41 and 45, the address of the error 
routine is specified as the last argument of the directive macro 
call. This results in a JSR PC, generated as part of the macro 
expansion . 

All of these get you to the error routines. They are all 
equivalent as long as you don't attempt to recover from the error. 
If you do recover, you must remember that a JSR PC or CALL pushes 
a return address onto the stack, as explained in the section on An 
Alternate Method for Error Checking. 



Run Time Conversion Routines 

As mentioned earlier, the system maintains task names, 
partition names, and certain other data in Radix-50 format to save 
space. There are times when conversions between ASCII and 
Radix-50 format need to be performed at run time. 

You can modify Example 2-1 (REQUES .MAC) so an operator can 
type in the task name at run time. This ASCII name would then 
have to be converted at run time to Radix-50 format because the 
. RAD 50 assembler directive can only be used at assembly time. The 
subroutine $CAT5 in SYSLIB.OLB is provided for performing this 
conversion. Its use is documented in Chapter 4 of the IAS/RSX-11 
System Library Routines Reference Manual . 

If the Get Task directive (GTSK$) is used to retrieve task 
information, the task name and partition name are returned in 
Radix-50 format. If you want to display these, you need to 
convert them to ASCII format. The subroutine $C5TA, also in 
SYSLIB.OLB and documented in Chapter 5 of the manual mentioned 
above, is provided for this purpose. 

Additional subroutines are provided for converting between 
binary and octal ASCII (signed or unsigned) and between binary and 
decimal ASCII (signed or unsigned). See Chapters 4 and 5 of the 
IAS/RSX-11 System Library Routines Reference Manual for additional 
information . 
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Notifying a Task When an Event Occurs 

Often a task needs to know when an event has occurred. The 
event may have occurred within another task; for example, when 
the task has completed a requested function. The event may 
instead have occurred within the system; for example, when a 
requested I/O operation is completed. The two methods for 
implementing synchronization are by using event flags and using 
asynchronous system traps. 



Event Flags 

There are three types of event flags: local, global (or 

common), and group global. Ninety-six event flags are made 

available to tasks, each with a unique number (1 (10) -96 (10) ) . 

Local event flags are provided for each task. There are 
32(10) local event flags, numbered 1 (10) -32 (10) . These flags are 
used to synchronize a task with an Executive service, such as an 
I/O transfer. One task cannot reference another task's local 
event flags, so they cannot be used to synchronize tasks with one 
another. Local event flags 2 5 (1 ) -32 ( 1 ) are reserved for system 
use and therefore should not be used by a user task. 

Global or Common event flags are provided for synchronization 
among different tasks. There is one set of 32(10) global event 
flags for the system, numbered 33 ( 10) -64 ( 10) . These flags can be 
referenced by any task. Global event flags 57 (10) -64 (10) are 
reserved for system use and should not be used by user tasks. 

NOTE 

There is no way to protect against other 
tasks using global event flags. Great care 
must be taken to ensure that global event 
flags aren't used at the same time by several 
different users. Check with your system 
manager before using any global event flag to 
ensure that it is not used for some other 
purpose. 
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There are only 32(10) global event flags available in the 
system. If additional event flags are needed, another set of 
event flags can be created for synchronization among different 
tasks. Group global event flags (32(10)), numbered 65 (10) -96 (10) , 
can be created for any UIC group number. These event flags can be 
referenced by any task running under the correct group number. 
Therefore, they can be used to synchronize tasks running under 
that group number. An additional advantage is that they cannot be 
referenced by tasks running under other group numbers. 

Group global event flags are created using the DCL SET GROUP 
FLAGS CREATE (FLA /CRE in MCR) command or the Create Group Global 
Event Flags (CRGF$) directive. When users in a group don't need 
them anymore, the group global event flags can be marked for 
deletion using the DCL SET GROUP FLAGS DELETE (FLA /ELIM in MCR) 
command or the Eliminate Group Global Event Flags (ELGF$) 
directive. After that, when all active tasks in the group have 
finished using them, the group global event flags are eliminated. 



Using Event Flags for Synchronization 

LEARNING ACTIVITIES 2-1 

Read section 2.2 on Event Flags in the 
RSX-11M/M-PLUS Executive Reference Manual . 
Pay particular attention to the examples. 
This section covers how event flags can be 
used for synchronizing tasks. This material 
will not be covered in this course. When you 
have finished reading the material, answer 
the following questions. The answers are 
provided in Appendix G. 

1. In Example 1 in the reading, how can Task 
B do some work while waiting for event 
flag 35 to be set by Task A? 

2. What would happen in Example 2 if a local 
event flag (e.g., 1) were used instead of 
a common event flag? 

3. Why is a local flag acceptable in 
Examples 3 and 4? 
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Examples of the Use of Event Flags for Synchronization 

Examples 2-6 and 2-7 show the use of event flags to 
synchronize two tasks. WFLAG creates the group global event flags 
for the group. It then clears event flag 65(10) and waits for 
that flag to be set. SFLAG sets event flag 65(10), which unblocks 
WFLAG. Run WFLAG first, then run SFLAG. 



The following notes are keyed to the examples. 

O Create the group global event flags - The default used 
here creates them for the group number which the task is 
running under. 

Q An error is reported if the flags already exist. This 
isn't a fatal error, so we check for this condition. If 
the flags do exist, print a message and continue. 

NOTE 

If the error address had been included in the 
macro directive call (CRGF$C , ,ERR1) , two 
changes must be made to the code. First, the 
check for IE.RSU must be made at location 
ERR1. Second, in the case of the nonfatal 
error IE.RSU, the stack will have one extra 
word because the macro does a JSR PC,ERR1, 
not a BCS ERR1. Therefore, you would need to 
either use a RTS PC (synonym RETURN) or, if 
you want to branch to another location, you 
need to pop the return address off the stack 
before branching. 

Q The flag is in an unknown state at startup. Therefore, we 
must clear the flag before waiting for it to be set. 

Q Wait for the event flag to be set by SFLAG. This causes 
WFLAG to be blocked. Now run SFLAG. 

Q Set event flag 65. This allows WFLAG to become unblocked. 
SFLAG now exits. 

O When WFLAG is unblocked and continues executing, it starts 
up here. Check for any directive error entering the Wait 
For state, print a message, and exit. 
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3 
4 

5 
6 
7 

8 

9 
10 
.1.1 
12 
3.3 
14 
15 
16 
17 
18 
19 
20 
21 



♦TITLE WFLAG 
♦I DENT /01/ 
♦ENABL LC 



f Enable lower esse 



? FILE WFLAG ♦ MAC 



5 This program creates the ^roup Global event flags y 

y clears event flag 65* and waits for it to be set* When 

* the flag is set it writes a message and exits* 

y 

t Assemble and task-build instructions* 

9 

9 MACRO/LIST LB i C 1 * 1 .IPROGMACS/LIBRARYy dev ♦ Cufdl'l WFLAG 

9 LINK/MAP WFLAG y LB* CI y 1 3PR0GSUBS/LIBRARY 

y 

y I n s t a 1 1 a n d R u n i n s t r u c t i o n s ♦ 
J 

y Run WFLAG y then run SFLAG* At least one of the 

y tasks must be installed? or else the RUN command 

y will tr« to install both tasks under the same 

9 namey TTnn* 



P'3 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 



♦MCALI 
♦ MCALI 
CLR 



EXIT*S>WTSE*C>CLEF*C>CRGF*C y System 

y macros 
TYPE y Supplied macro 



STARTt CLR R0 y R0 used to identify 

y the error 

TYPE < WFLAG IS CREATING THE GROUP GLOBAL EVENT FLAGS 
CRGF$C 5 Create group global 

y event flags 
BCC OK 5 Branch on directive ok 

y If group global event flags already exist y 
y Just display message and continue 

CMP *DSW?#IE*RSU y Check for efs already 

y in existence 
BNE ERR1 y Branch on any other 

y dir error 

TYPE <GR0UP GLOBAL EVENT FLAGS ALREADY EXIST> 
OKI TYPE <CLEAR AND THEN WAIT FOR EF 65* TO BE SET> 

CLEF*C 65* y Clear event flag 65* 

BCS ERR2 ? Branch on directive 

5 error 

WTSE$C 65* y Wait for event flag 65 

y to be set 
BCS ERR3 y Branch on directive 

5 error 

<EF 65* HAS BEEN SET* WFLAG WILL NOW EXIT> 



ERR3 * 
ERR2 1 
ERR1 i 



TYPE 
EXIT*S 

INC 

INC 

INC 

MOU 
I OT 
* END 



RO 
RO 
RO 

*DSWyRl 
START 



? RO = 3 if error on 

y wait for dir 

y RO ~ 2 if error on 

y clear flag dir 

y RO ~ 1 if error on 

5 create group flags dir 

? Place DSW in Rl 

y Trap and dump registers 



Example 2-6 Waiting for an Event Flag (Sheet 1 of 2) 
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Run Session 

>INS WFLAG 
>INS SFLAG 
>RUN WFLAG 

WFLAG IS CREATING THE GROUP GLOBAL EVENT FLAGS 
CLEAR AND THEN WAIT FOR EF 65 ♦ TO BE SET 
RUN SFLAG 

EF 65* IS BEING SET ♦ THEN SFLAG WILL EXIT* 
EF 65* HAS BEEN SET* WFLAG WILL NOW EXIT 



Example 2-6 Waiting for an Event Flag (Sheet 2 of 2) 
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i 








1 

<5 




A 
*t 




cr 








6 




/ 




O 
O 




o 

7 




10 




1 1 




J. a. 




•I "JE 




•1 j! 
.1 *f 




1 vJ 




1 6 




17 




18 




19 




20 




21 




22 




23 




24 




25 




26 


e 


27 




28 




29 




30 




31 




32 



♦TITLE SFLAG 
♦ I DENT /01/ 
♦ENABL LC 



f Enable lower case 



y + 



FILE SFLAG ♦ MAC 



This task sets event flag 65* It assumes that the 
group global event flags have already been created* 

Assemble and task-build instructions* 

MACRO/LIST LB5C1 » 1 3PR0GMACS/LIBRARY s> dev J Cuf dUSFLAG 
LINK/MAP SFLAG ? LB : C 1 * 1 3PR0GSUBS/LIBRARY 

Install and Run notes* 

First run WFLAGy then run SFLAG* At least one of 
the tasks must be installed)' or else the RUN 
command will try to install both tasks under 
the same name? TTnn* 



♦MCALL EXIT*SrSETF*C 
♦ MCALL TYPE 



r System macros 
? Supplied macros 



START i TYPE 

SETF$C 
BCS 

EXIT*S 
err: MOV 
IOT 
♦ END 



<EF 65* IS BEING SET ♦ THEN SFLAG WILL EXIT* 

65* r Set event flag 65* 

ERR f Branch on dir error 

$ Exit 

$DSWyRl 5 Save DSW 

i Trap and dump registers 

START 



Example 2-7 Setting an Event Flag in a Task 
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Asynchronous System Traps (ASTs) 

Asynchronous System Traps (ASTs) are used to detect events 
that occur asynchronously to a task's execution. Two examples are 
the completion of an I/O transfer and a power up after a power 
failure. We say that they occur asynchronously to a task's 
execution because they occur at unpredictable times, depending on 
conditions which the task cannot control. If a task needs to do 
work while waiting for an event to occur, it can do so and 
periodically check an event flag to detect the event. However, 
this means that the task must stop its work to check the flag. 

Using an AST gives the Executive the responsibility for 
monitoring the event. The Executive will "interrupt" the task and 
transfer control to a special user-written routine when the event 
has occurred. This technique is more efficient because the task 
doesn't have to do any checking. It also results in faster 
notification because the task is notified immediately after the 
event occurs. With checking of the flag, it may take a long time 
to notice an event that has occurred immediately after a check. 

Several Executive directives allow the use of ASTs to handle 
synchronization. A complete list appears in the section 5.1.5 on 
Trap Associated Directives in the RSX-11M/M-PLUS Executive 
Reference Manual . 

Figure 2-6 shows how an AST works. The following notes are 
keyed to this figure. 

O The user specifies an AST routine in an Executive 
Directive. The Executive sets up for the AST. 

Q The Executive returns control to the user task. 

Q When the system determines that the event which 
corresponds to the specified AST routine has occurred, the 
Executive passes control to the AST routine and the task 
executes it before any other user code in the task. This 
means that if the task is executing at the time of the 
AST, the task is "interrupted" until the AST routine is 
executed. The AST routine is executed even if the task is 
stopped or blocked. In that case, the task returns to its 
stopped or blocked state after the AST routine is 
executed, unless the AST routine or some external event 
unstops or unblocks the task in the meantime. 
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TASK CODE EXECUTIVE CODE 




TK-7508 



Figure 2-6 AST Mechanics 



Q The AST routine is a user written routine contained within 
the task. The user stack is set up in a special way by 
the Executive before the AST routine is entered, as shown 
in Figure 2-7. Notice that some ASTs have special words 
added to the stack. The AST routine may use these 
parameters to check on what caused the AST, and then take 
appropriate action. See section 2.3.4 on AST Service 
Routines in the RSX-1 1M/M-PLUS Executive Reference Manual 
for a discussion of the specific stack formats. 
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Finally, the AST routine uses the ASTX$S Executive 
directive to "return" control to the main task code via 
the Executive. When the ASTX$S directive is invoked, the 
Executive assumes that the stack contains only the 
standard first four AST stack words. The user AST routine 
must clear any additional AST specific parameters off the 
stack before issuing this directive. 

O The Executive checks for any other ASTs which may have 
occurred while the AST routine was executing. Any such 
additional ASTs are queued up in an AST pending queue in a 
first-in-first-out order. These ASTs are also serviced 
before the Executive "returns" to the "interrupted" state 
and code. 

Note that the task's general purpose registers R0 through R5 
and SP are not saved. Therefore, if you use these registers in an 
AST routine, you must save and restore them. 

For additional information on ASTs, see sections 2.3.3 and 
2.3.4 on ASTs and AST Service Routines in the RSX-11M/M-PLUS 
Executive Reference Manual. 
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INCREASING 
ADDRESSES 



NEW SP 



▼ OLD 

STACK 

POINTER 

(SP) 



TASK'S DIRECTIVE STATUS WORD 



PSW OF TASK PRIOR TO AST 



PC OF TASK PRIOR TO AST 



EVENT FLAG MASK WORD 



AST SPECIFIC 
PARAMETERS 



STANDARD 
AST PARAMETERS 
ALWAYS PASSED 
ON THE STACK 



Figure 2-7 Stack as Set Up by the Executive for ASTs 



Example 2-8 shows the use of ASTs. An AST routine is entered 
if an abort request is made by either another task or an operator. 

The following notes are keyed to the example. 

O Set up for AST on abort attempt. 

O Loop until abort request comes in. 

Q Service routine entered on first abort request. For this 
AST, a nonpr ivileged task enters the routine only once and 
further ASTs are cancelled. If the task is built as a 
privileged task, the routine is entered each time an abort 
attempt comes in. See Appendix D for an explanation of 
privileged tasks. 

Q There is no need to set up the stack for the AST return, 
because there are no AST specific parameters (only the 
four words expected by the Executive are on the stack) . 
The AST exit causes the Executive to transfer control to 
the task back in the main code where it was "interrupted." 

Another directive, SREX$, gives extended capabilities. An 
entry passed on the stack to the AST routine indicates whether the 
abort request came from a privileged or nonpr ivileged task or user 
and further, whether it came from an Abort Task directive or a DCL 
(or MCR) command. Each case can be handled differently. 
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♦TITLE ASTEX 



4 

5 
6 
7 
8 
9 
10 
11 
12 
.1.3 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
'28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 



? FILE ASTEX* MAC 
t 

r This task sets up a Specify Request Exit AST routine* 

? It then sits in a loop until someone tries to abort 

i it* At that point* it enters the AST routine and sends 

r out a message* It won't abort the first time* A second 

9 abort attempt will succeed because for this particular 

9 AST* the first 3bort AST cancels any further abort 

9 AST's* 

9 

i Assemble and task -build instructions* 

9 

? >MACR0/LIST ASTEX-LB* CI y 1 3PRQGMACS/LIBRARY y - 

y ->devICufd3ASTEX 

9 >LINK/MAP ASTEX y LB* CI y 1 3PR0GSUBS/LIBRARY 



start: 

9 Do s 

loop: 

r Er ro 

erri: 



* MCALL 
♦ MCALL 

CLR 

SREA*C 

BCS 

TYPE 
ome work* 

CLR 

INC 

BR 
r code 

INC 

MOV 

I0T 



SREA$CyASTX*S 
TYPE 

RO 

REXAST 
ERR! 



:.ASTEX STARTING UP* WILL WORK UNTIL ABORTED ♦ 



R2 
R2 

LOOP 



External system macros 
External supplied macros 

Error count 

Set up Specify Exit AST 
Branch on dir error 



Clear counter 
Increment counter 
Loop back 



RO J Error count 

$DSW?R1 i Move DSW for display 

Trap and display 
registers 
9 AST service routine 

REXAST : TYPE <TRYING TO ABORT ME y EH?> y Display 

TYPE <WE WON'T LET YOU THIS TIME!> ? message 
ASTX*S 9 AST exit 

♦END START 



Run Session 

>INS ASTEX 
>RUN ASTEX 

ASTEX STARTING UP* WILL. WORK UNTIL ABORTED* 
ABORT/TASK ASTEX 

TRYING TO ABORT ME* EH? 
WE WON'T LET YOU THIS TIME ! 
ABORT/TASK ASTEX 

10:57:02 Task "ASTEX u terminated 

Aborted via directive or CLI 



Example 2-8 Using a Requested Exit AST 
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Example 2-9 shows the use of an AST routine with the Mark 
Time (MRKT$) directive. The AST routine is entered after a 10. 
second time period expires. The task starts the time period and 
then suspends itself until the 10. seconds go by. The AST 
routine, when entered, resumes the task. Therefore, the task is 
unblocked and continues to execute when the AST routine exits. 
The "main" code then displays a message and exits. 

The following notes are keyed to the example. 

O The Mark Time instructs the system to start the 10. 
second interval. The two specifies seconds. After that, 
the AST routine at ASTSRT is entered. The missing first 
argument is for an event flag, which would, if specified, 
be initially cleared and then set when the 10. seconds 
expired . 

Q Task suspends itself. The AST routine is entered even 
though the task is suspended. 

O The AST routine resumes the task. Otherwise, the task 
would return to a suspended state upon exit from the AST 
routine . 

Q This instruction cleans up the stack for the AST Exit 
directive. The extra word contains the event flag number 
of the event flag set, or zero (in this case) if none was 
specified. This word could be used to distinguish which 
MRKT$ directive had expired in the case of several MRKT$ 
directives, using different event flags but the same AST 
routine . 

Q After the task is resumed by the AST routine, it starts 
here . 

If a task uses the Mark Time directive to place a time limit 
on an operation, the Mark Time can be cancelled using the Cancel 
Mark Time directive if the operation completes before the time 
limit expires. 
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1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
.11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
4.1 
42 
43 
44 
45 



♦TITLE MARK 
♦ I DENT /0.1/ 
♦ENABL LC 



? Enable lower case 



$ FILE MARK* MAC 



r This program issues a mark time for 10 seconds and 

r then stops itself* When the mark time expires? an AST 

t routine is invoked which unstops the task* 

» 

y Assemble and task-build instructions* 



MACRO/LIST LB t C 1 1 1 3PR0GMACS/LIBRARY y dev : Cuf d 3 MARK 
L INK/MAP MARK y LB * C 1 1 1 3PR0GSUBS/LINRARY 



y Install and run instructions* 



The task must be installed under the name MARK in 
order to run correctly 



* MCALL 



♦ MCALL 



EXIT$S y MRKTsC y ASTX$S r SPNDSS y RSUM*C 

5 System macros 
TYPE y Special supplied macro 



START ♦ CLR 



LRR3 ♦ 
ERR2* 
ERR1 : 



TYPE 
TYPE 
MRKT*C 

BCS 

SPND*S 

BCS 

TYPE 

EXIT$S 

INC 

INC 

INC 

MOV 
IDT 



RO 

<"MARK ' 
<ITSELF 
ylO* y2y ASTSRT 
ERR 1 



ERR2 

< ' MARK ' 

RO 

RO 

RO 

*DSWyRl 



y RO is used to identify 

? errors 
IS RUNNING AND WILL SUSPEND> 

UNTIL AST RESUMES IT> 

y Issue mark time 

y Branch on directive 

y error 

y Suspend task 

y Branch on directive 

y error 
IS RESUMED AND WILL EXIT> 

y Exit 

y RO ~ 3 if error on 

y unstop 

y RO ~ 2 if error on 

y mark time 

y RO - 1 if error on 

y stop 

? Save DSW 

y Abort task and dump 

y registers 



Example 2-9 Using an AST in the Mark Time Directive 

(Sheet 1 of 2) 
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f AST SERVICE ROUTINE 

r 

ASTSRT: TYPE <AST ROUTINE EXECUTING AND WILL UNSTOP 'MARK'> 
RSUM$C MARK r Resume task 

BCS ERR3 ? Branch on directive 

? error 

r User must clean AST specific values off the stack so 
? that the Exec gets control with stack as expected 
r (with regular 4 AST words) 

TST (SP)+ t Clean off stack for 

r AST return 
ASTX$S r Return to main code 

r through ast exit 

♦END START 



Run Session 

> INST ALL MARK 
>RUN MARK 

"MARK ' IS RUNNING AND WILL SUSPEND 
ITSELF UNTIL AST RESUMES IT 

AST ROUTINE EXECUTING AND WILL UNSTOP 'MARK' 
'MARK' IS RESUMED AND WILL EXIT 



Example 2-9 Using an AST in the Mark Time Directive 

(Sheet 2 of 2) 



Synchronous System Traps (SSTs) 

There is another kind of system trap available on the system, 
generally used if you wish to handle trap producing errors 
yourself, rather than have the Executive handle them. They are 
called Synchronous System Traps (or SSTs) . They detect certain 
events which occur when program instructions are executed (e.g., 
odd address traps and memory protect violations) . They are 
synchronous because they always occur at the same point in the 
program, when a given trap-causing instruction is executed. 

LEARNING ACTIVITY 2-2 

Read sections 2.3.1 on Synchronous System 
Traps and 2.3.2 on SST Service Routines in 
the RSX-11M/M-PLUS Executive Reference Man- 
ual . Pay particular attention to the section 
on SST service routines. 



46 

47 
48 

A 49 
O 50 

51 

5? 

53 

54 

55 

57 
58 
59 
60 
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To set up for user coded SSTs, you must set up a vector table 
in a data area that contains a list of SST service routine 
addresses. Each entry in the table corresponds to a specific SST 
which may occur. A zero in an entry indicates that the Executive 
should handle that trap. Refer to Figure 2-8, which shows the 
setup and use of an SST routine. The following comments are keyed 
to this figure. 

O At start-up, the task issues a SVTK$ or SVDB$ directive, 
specifying the vector table address, which causes the 
Executive to record that address, setting up for user SST 
service routines. 

O Tne Executive returns control to the task. 

Q An instruction is executed which causes a trap. The 
Executive checks the SST vector table to see if the user 
has specified a routine to handle the trap. If one is 
specified, the Executive sets up the user stack and 
transfers control to the SST routine. If no SST routine 
is specified, the Executive aborts the task and displays 
an error message at TI:. 

Q Once the task receives control again, it executes the SST 
routine as if in the main code. All system services are 
available to the task. To return to the main code, clean 
up the stack so it contains only the return PC and PSW, 
and execute an RTT or RTI instruction. 

O The RTT or RTI instruction causes the PC and PSW to be 
popped from the stack into the appropriate register, 
causing a return to the "interrupted" code. 

Note that the general purpose registers R0 through R5 and SP 
are not saved. Therefore, if you use these registers in an SST 
routine, you must save and restore them. 
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TASK CODE 



EXECUTIVE CODE 



DATA ( 
AREA 



MAIN 
CODE 



SST 
SERVICE { 
ROUTINE 



SST VECTOR TABLE 



SVTK$ DIRECTIVE 



BPT INSTRUCTION 




BPTSST: 



RTI OR RTT 




SET UP POINTER 

TO SST VECTOR TABLE 



EXECUTIVE TRAP 
SERVICE ROUTINE 



Figure 2-8 SST Sequence 



Example 2-10 uses three SST service routines to handle BPT, 
IOT and memory protection violation traps in the user program. 
The following notes are keyed to this example. 

O Vector table containing the SST service routine addresses. 
See the documentation on SVTK$ in Chapter 5 of the 
RSX-11M/M-PLUS Executive Reference Manual for the order of 
words in the table. 

O Executive directive to permit the use of user SST service 
routines. You can also use SVDB$ to trap to an external 
debugger (e.g., ODT) instead of to the user code. 

O BPT causes a trap. The Executive checks the vector table; 
because a routine address is specified for BPTs , it sets 
up the stack and transfers control to location BPT. 



The BPT SST routine displays a message, then returns 
trap, to line 28. 



from 
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The CLR 120000 causes a memory protect violation since the 
highest address used in this program is far below that 
(1627(8)). This causes another SST. 

On a Memory Protect Violation SST, the Executive passes 
three more words on the stack in addition to the PC and 
the PSW. The details on these words are discussed in 
section 2.3.2 on SST Service Routines in the 
RSX-11M/M-PLUS Executive Reference Manual . 

We don't need the stack values in this routine, but we do 
need to pop them off the stack so that the RTI instruction 
works properly. The CMP and the TST are "dummy" 
instructions used to pop the three words off the stack. 

IOT causes another SST. 

In the IOT routine, we can alter the return PC (on the top 
of the stack) , which changes the return point for the RTI 
to NEW. 

The TRAP instruction causes an SST for which there is no 
user specified routine. Therefore, the Executive aborts 
the task and displays a message at TI:. 
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♦ TITLE SST 

♦ I DENT /Ol/ 
♦ENABL LC 



r Enable lower case 



6 
7 
8 
9 
10 
.11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 

4fc 24 

%J 25 

O 27 
028 

29 
30 

O 3i 

32 
33 

34 
35 
36 
37 
38 
39 
40 
41 
L42 
43 
44 
45 
46 
47 
48 
49 
50 



O 

O 



y FILE SST ♦ MAC 
y 

i This task sets up an SST vector table to handle SST's 

5 for BPTy IOTy and odd address traps* It then executes 

f instructions to cause these traps to occur* In each 

i SST routine y a message is displayed and then the task 

y continues* Finally? a TRAP instruction is executed* 

r Since no user SST routine is specified for TRAP y the 

y Executive aborts the task* 
t 

y Assemble and task-build instructions* 



MACRO/LIST LB ♦* C 1 y 1 3PR0GMACS/LIBRARY y dev X tuf dDSST 
LINK/MAP SST y LB* C 1 y 1 3PR0GSUBS/LIBRARY 



VTABLE: 
y 

start: 



new : 

y 

y SST 



♦MCALL 
♦MCALL 

♦ WORD 

SvTK$C 

BPT 
CLR 



I0T 

EXIT$S 
TRAP 



routines 
y 

MPTVI0: TYPE 

CMP 
TST 



BPT ♦ 

iot: 



RTI 

TYPE 

RTI 

TYPE 

MOV 



RTI 
♦ END 



SvTK*CyEXIT*S 
TYPE 



y External system macros 
y External supplied macro 



OyMPTVIOyBPTylOT y SST vector table 



VTABLEy4 



120000 



Have Executive set up 

SST table 

BPT instruction 

Clear location 120000y 
causing a memory 
protect violation 

IOT instruction 

Exit 

TRAP instruction 



<MEM0RY PROTECT VIOLATION CAUGHT> y Type 



(SP)+y (SP) f 
( SP ) + 



<bpt caught!: 
<iot caught: 

♦NEWy (SP) 



START 



message 
Clean off three 

specific stack words 

for memory protect SST 
Return from trap 
Type message 
Return from trap 
Type message 
Change PC on stack so 

return from trap 

returns to NEW 
Return from trap 



Example 2-10 Using SSTs (Sheet 1 of 2) 
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Run Session 

>RUN SST 
BPT CAUGHT 

MEMORY PROTECT VIOLATION CAUGHT 
.TOT CAUGHT 

14*07:50 Task "TT11 " terminated 
TRAP execution 
R0=001573 
R 1*0000 12 
R2=000000 
R3= 1.403 12 
R4« 144000 
R5=000000 
SP-001254 
PO001312 
PS^ 170000 



Example 2-10 Using SSTs (Sheet 2 of 2) 



Now do the tests/exercises for this module in the 

Tests/Exercises book. They are all lab problems. Check your 

answers against the solutions provided, either in that book or in 
on-line files, under UFD [202,2]. 

You will need the program READF.MAC to do question 1. It 
should be available on-line (probably under UFD [202,1]). In case 
it is not available on-line, the source code is listed in Appendix 
G. 

If you think that you have mastered the material, ask your 
course administrator to record your progress in your Personal 
Progress Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, 
return to this module for further study. 
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USING THE QIO DIRECTIVE 



INTRODUCTION 

All input/output under RSX-11M is performed using the QIO 
directive. In this module, you will learn how to use the QIO 
directive, concentrating on its use for input/output to a 
terminal . 



OBJECTIVES 

1. To use the QIO directive to perform I/O to a device that 
is not file-structured (e.g., a terminal) 

2. To choose either synchronous or asynchronous I/O as the 
most effective method for a given application 

3. To perform complete error checking upon I/O completion 

4. To use formatting routines from the system subroutine 
library to improve the readability of output data. 



RESOURCES 

1. RSX-11M/M-PLUS Executive Reference Manual , specific 
directives in Chapter 5 

2. RSX-11M/M-PLUS I/O Driver's Reference Manual , Chapters 1, 
2 and 3 

3. IAS/RSX-11 System Library Routines Reference Manual , Chap- 
ter 6 
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OVERVIEW OF QIO DIRECTIVES 

All I/O operations under RSX-11M are performed using QIO 
directives. The QIO directive causes an I/O request to be passed 
to the appropriate service routine. The service routine is either 
a device driver or a system task called an ancillary control 
processor (ACP) . There is a device driver for each device type on 
the system. There are three ACP's provided: F11ACP for FILES-11 
structured disks, MTAACP for ANSI magtape, and NETACP for DECNET. 

The I/O packet is placed in an I/O queue for the service 
routine. The packets are queued up in order according to the 
priority of the issuing tasks. If there are multiple requests at 
a given priority, those requests are queued first-in-first-out 
(FIFO). The QIO directive does not perform the I/O operation 
itself, but simply queues the request to the appropriate service 
routine, which performs the actual I/O transfer. After the I/O 
request has been queued, the Executive returns control to the 
issuing task, unless the task requests the Executive to place the 
task in a Wait For state until the I/O transfer completes. 



PERFORMING I/O 

QIO directives are generally used only for I/O on non-file 
structured devices such as terminals. For file I/O, the File 
Control Services (FCS) or Record Management Services (RMS) are 
used, which in turn issue the appropriate QIOs for you. 

When using QIOs, you need to specify which I/O operation 
(e.g., Read Virtual Block or Write Virtual Block) is to be 
performed by means of an I/O function code. Specify the device by 
means of the logical unit number (LUN) . To specify additional 
information about the I/O operation (e.g., what buffer to write 
and how many characters), use an I/O Parameter List (IOPL) . All 
of this information is passed to the Executive through parameters 
in the Directive Parameter Block (DPB) , as it is with all 
Executive directives. 
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I/O FUNCTIONS 

Each device type has its own set of legal I/O functions. 
Certain functions are called standard or common, since they are 
available on all devices. The seven standard I/O functions are 
listed in Table 3-1. Logical block transfers (Read Logical Block 
and Write Logical Block) can usually be performed for any device. 
For file-structured devices, virtual block transfers can be 
performed only if a file is open on the device. If Virtual Block 
I/O is requested for a device which is not file-structured, such 
as a terminal, it is converted to logical block I/O for you. 
Devices may have additional device specific functions, such as 
read no echo at a terminal. Each function requires its own set of 
parameters, which are specified in an I/O parameter list. 



Table 3-1 


Common 


(Standard) I/O Function Codes 


Global 


Octal 




Symbol 


Value 


Function 


10. ATT 


001400 


Attach device 


IO.DET 


002000 


Detach device 


IO.KIL 


000012 


Cancel I/O requests 


IO.RLB 


001000 


Read Logical Block 


I . RVB 


010400 


Read Virtual Block 


IO.WLB 


000400 


Write Logical Block 


I . WVB 


011000 


Write Virtual Block 
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Logical Unit Numbers (LUN) 

The device for an I/O operation is specified by means of a 
logical unit number. The correspondence between logical unit 
numbers and physical devices is made initially at task-build time. 

The default LUN assignments set up by the Task Builder are as 
follows : 



LUN 


#1 


- SY: 


LUN 


#2 


- SY: 


LUN 


#3 


- SY: 


LUN 


#4 


- SY: 


LUN 


#5 


- TI: 


LUN 


#6 


- CL: 



These default assignments may be overridden at task-build 
time by using the ASG option. Additional LUNs can be created (up 
to a maximum of 250(10)) by using the UNITS option. 

Once a task is installed, an operator can check the LUN 
assignments for the task by using the DCL SHOW LOGICAL_UNITS 
command (LUN in MCR) . The assignments can be changed by an 
operator using the DCL ASSIGN/TASK command (REA in MCR) . The LUN 
assignments can also be checked at run time using the Get LUN 
directive (GLUN$) , and changed using the Assign LUN directive 
(ALUN$) . 



Synchronous and Asynchronous I/O 

There are two kinds of I/O, synchronous I/O and asynchronous 
I/O. With synchronous I/O, the Executive provides all 
synchronization. With asynchronous I/O, you must provide 
synchronization regarding the completion of the I/O operation 
itself. 

When a task issues a synchronous I/O request, it doesn't get 
control back from the Executive until after: 

1. The I/O packet is queued, and 

2. The I/O operation (the transfer performed by the service 
routine) itself is completed. 

In other words, the synchronous I/O request asks the Executive to 
queue the I/O packet and then place the task in a Wait For state, 
to wait until the specified event flag is set, signifying that the 
actual I/O operaton is complete. 
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Figure 3-1 shows the flow of instructions during the 
processing of a QIO directive. The task does not execute the 
instruction following the QIO directive until after the I/O 
transfer itself has completed. Figure 3-2 shows a time diagram 
illustrating the same I/O operation. Note that once the QIO 
directive is executed at step 1, the task doesn't execute again 
until step 8, after the transfer has completed. The system 
handles all synchronization with synchronous I/O. Use the QIOW$ 
directive to invoke this type of I/O. 



Commentary to Figures 3-1 and 3-2: 

O User task executes QIO and Wait For directives. 

Q Executive queues the I/O request. 

Q Executive calls the driver. 

Q Driver begins the I/O transfer. 

Q Driver handles the I/O transfer as necessary. 

O 1/0 transfer completes. 

O Driver finishes its work and notifies the task that the 
I/O is completed. 

O User task continues. 



96 



USING THE QIO DIRECTIVE 



EXECUTIVE 



USER TASK 



JQIO DIRECTIVE 




I/O PACKET 



) 



I/O QUEUE 



Figure 3-1 Execution of a Synchronous I/O Request 



USER TASK 
QIO DIRECTIVE 
DRIVER 

I/O TRANSFER 



e o 



OS 



TIME 



Figure 3-2 Events in Synchronous I/O 
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With asynchronous I/O, the Executive still queues the I/O 
request. When a task issues an asynchronous I/O request, the 
Executive passes control back to the task immediately after the 
I/O packet is queued to the driver. You must provide 
synchronization concerning the completion of the actual I/O 
transfer. This could occur at various times, depending on such 
factors as how many other I/O packets are ahead of this one in the 
driver's I/O queue, and the speed of the device itself. The task 
executes in parallel with the I/O request. 

In Figure 3-3, the instruction after the QIO request is 
executed after the I/O packet is queued (and the driver has 
started the transfer), not after the I/O transfer completes. The 
task continues executing unless it chooses to wait. Figure 3-4 
shows a time diagram illustrating asynchronous I/O. 

Note that after the QIO directive is executed at step 1, the 
task begins executing again at step 5. In this example, the task 
waits for the I/O transfer to complete at step 5a . If you use 
asynchronous I/O, you must provide any synchronization yourself, 
using event flags, asynchronous system traps, or both. The task 
shown in Figures 3-3 and 3-4 uses a Wait For Single Event Flag 
directive at step 5a. Use the directive QIO$ to invoke this type 
of I/O. 

The advantage of asynchronous I/O is that a task can continue 
processing in parallel with the I/O transfer. For example, you 
can perform computations while waiting for a read or write to 
complete. Of course, if you need the information from the read 
before you can do anything else, it is better to use synchronous 
I/O. 
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Commentary to Figures 3-3 and 3-4: 
O User task executes the QIO directive. 
O Executive queues the I/O request. 
O Executive calls the driver. 

O Driver begins the I/O transfer; Executive passes control 
back to the user task. 

Q Driver handles the I/O transfer as necessary. User task 
executes in parallel with the I/O transfer. 

a. User task waits for the I/O operation to complete. 

O I/O transfer completes. 

Driver finishes up and the Executive notifies the task 
that I/O is completed. 

Q User task continues. 
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EXECUTIVE 




QIO DIRECTIVE 
ROUTINE 




TK-7518 

Figure 3-3 Execution of an Asynchronous I/O Request 



USER TASK 

QIO DIRECTIVE 

DRIVER 

I/O TRANSFER 



o 



eo 



o 



TIME 



Figure 3-4 Events in Asynchronous I/O 



TK-7513 
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MAKING THE I/O REQUEST 

Specify the following information in the QIO$ or QIOW$ call 
when requesting I/O. 

• Synchronous or asynchronous I/O, by using the appropriate 
directive . 



• The I/O function to be performed. 

• The LUN to be used for the I/O operation. 

• An event flag number, if any, to be used for 
synchronization. This is required for synchronous I/O. 

• The address of an I/O Status Block (IOSB) - two words set 
aside with . BLKW or . BLKB assembler directives. The IOSB 
is used to pass status and other information about the I/O 
operation back to the task. 

• The address of an AST routine, if transfer to an AST 
routine is desired upon completion of the I/O transfer. 

• The I/O parameter list (up to six words) which specifies 
information for the particular device and for the 
particular I/O function requested. 

Table 3-2 shows the I/O parameter list arguments which are 
needed for each of the standard I/O functions with the full-duplex 
terminal driver. Table 2-3 (in section 2.3 on the QIO Macro) in 
the RSX-11M/M-PLUS I/O Driver's Reference Manual lists these 
standard functions and the other device-specific functions 
available with the full-duplex terminal driver. The 
device-specific functions will be discussed further, later in this 
module. If your RSX-11M system has the half-duplex terminal 
driver, Table 3-3 in section 3.3 on the QIO Macro lists the 
functions available with that driver. For other devices, there is 
a corresponding table in the appropriate chapter of the manual. 
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Table 3-2 I/O Parameter List for Standard I/O Functions 
Function i/o Parameter List 

Attach None needed 

Detach None needed 

Kill None needed 



Read Virtual Block 

llllH^ 

Read Logical Block 



Write Virtual Block 
Write Logical Block 



Word 1 - Buffer starting address 
Word 2 - Buffer size (in bytes) 
Word 3 - Optional timeout count 

(in 10 second intervals) 
NOTE: Word 3 is Only used if a 
special subfunction bit 
is set. See this module's 
section on Terminal I/O. 
Words 4, 5, and 6 - Unused 



Word 1 
Word 2 
Word 3 



Octal 
Value 

040 

060 

061 

044 



Buffer starting address 
Buffer size (in bytes) 
Vertical format control, 
as follows: 



ASCII 
Character 

Blank 

IlIIIIIlllllllllllIIIIIIIII 
■■■■ 



053 
000 



IIIIIII 
Null 



Meaning 

Single space 

Double space 

Form feed 

Prompting output- 
stay in same 
location after 
output 

Overprint 

No implied format 
control - use 
internal control 



Words 4, 5, and 6 - Unused 
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Error Checking and the I/O Status Block 

There are two kinds of errors which can be produced by QIO 
directives, directive errors and I/O errors. The various 
directive and I/O status codes and their meanings are listed in 
Appendix B of the RSX-11M/M-PLUS I/O Driver's Reference Manual and 
also in the RSX-11M Mini -Reference . 

Directive errors occur because of errors in processing the 
directive and getting the I/O packet queued up to the device 
driver. As with all directives, directive errors are indicated by 
a negative value in the DSW and the carry bit set upon return to 
the task code. Success is indicated by a positive value 
(typically +1) in the DSW and clearing of the carry bit. 
Therefore, the directive status indicates the success or failure 
of the attempt to queue the I/O packet. Check for directive 
errors immediately upon return after the QIO directive is issued. 

Upon completion of the I/O transfer itself, the Executive 
returns status information about the I/O transfer to the I/O 
Status Block, laid out as follows: 



Device 


Dependent 


I/O Status 


Actual 


Number of 


Bytes 


Transferred 



NOTE 

The low-order byte of the first word of the 
I/O Status Block contains the I/O status 
code. This is a byte value, not a word 
value. A positive I/O status code (usually 
+1 = IS. SUC) indicates success. Again, 
negative values indicate various error 
conditions. The second word of the I/O 
status block indicates the number of bytes 
actually transferred, which is significant in 
the case of any read or a write which ends 
after only some of the data is transferred. 
The device dependent byte usually contains 
information which is device dependent. For 
example, for a read from a terminal, it 
contains the character which was typed as a 
terminating character (<RET>, CTRL/Z, <ESC>, 
etc . ) . 
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The I/O status byte should be checked only after the I/O 
transfer completes. For synchronous I/O, the I/O status should be 
checked right after checking the DSW, since the I/O transfer 
itself also completes before control is returned to you. For 
asynchronous I/O, on the other hand, the I/O status should be 
checked when the task is notified by the Executive that the 
transfer is complete. Synchronization is discussed in the section 
that follows, after an example of synchronous I/O. 
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THE QIO DIRECTIVES 



Synchronous I/O 

The format of the QIOW$ call is: 

QIOW$ i fn , lun ,ef n ,pr i , iosb f ast , iopl 

where 

ifn - I/O function code 
lun - Logical unit number 

efn - Event flag number (required for synchronous I/O) 

pri - Priority (not used) 

iosb - I/O status block address 

ast - AST routine address 

iopl - I/O parameter list 

Example using the $S form: 

. MCALL QIOW$S 



BUFF: .ASCII /HERE IS THE MESSAGE/ 
LBUFF: =.-BUFF 
.EVEN 

IOSB: . BLKW 2 



QIOW$S #I0.WVB,#5,#1, f #IOSB, ,<#BUFF f #LBUFF,#40> 



Explanation of QIO arguments: 

Write Virtual Block 

LUN 5 (TI:) 

Event flag #1 

Priority (always ignored) 

I/O status block address = IOSB 

AST routine address (none specified) 

I/O parameter list 

Input buffer address = BUFF 

Buffer length = LBUFF 

Vertical format control = 40(8) for single space 
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Once again, the $ f $C , or $S form of the directive may be 

used. An event flag must be specified for synchronous I/O. If 

one is not specified, the I/O request is handled as an 

asynchronous I/O request. The priority is included to allow 
compatibility with RSX-11D. It is not used in RSX-11M. 

ASTs are not generally used for synchronous I/O, because the 
Executive performs all synchronization for you. The I/O parameter 
list is a single directive parameter. Therefore, the list is 
enclosed in angle brackets, with the elements separated by commas. 
In fact, six words are always placed in the DPB for the I/O 
parameter list, whether or not all six words are specified. 

Example 3-1 shows the use of synchronous QIOs. The following 
notes are keyed to the example. 

O As with other directives, the macro names must be 
specified in a .MCALL statement. Note that in this 
example, we use both the $C form and the $S form of the 
QIOW$ directive. 

O The two-word I/O status block for return of I/O status. 

Q The buffer into which the data will be read, and also from 
which the data will be displayed. 

O R4 is used to indicate whether a QIO error is a directive 
error or an I/O error. A value of zero indicates that a 
directive error occurred (and that R3 will contain the DSW 
value). A value of -1(177777(8)) indicates that an I/O 
error occurred (and that R3 will contain the I/O status 
byte) . 

O Issue the read request. We are using LUN 5, event flag 1, 
and IOSB is the label of the IOSB. The I/O parameter list 
is set up as a single parameter (hence the need for the 
angle brackets (< and >)). It specifies BUFF, the 
address of the buffer for the characters read and 80. , the 
maximum number of characters to read. If input is 
terminated with a terminating character, such as a 
carriage return, before 80 characters are typed in, the 
number of characters actually read will be returned in the 
second word of the IOSB. Input will be terminated 
automatically after the 80th character, if 80 characters 
are typed. In that case, 80 will be returned as the 
number of characters read. 
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Check for directive error - indicating a failure in 
queueing the I/O packet. 

With synchronous I/O, we don't get control again until 
after the I/O operation has completed, so also check the 
I/O status. A value less than zero indicates an error in 
the I/O transfer. 

Get the count of characters typed in from the second word 
of the IOSB. We will only check on and convert that many 
characters . 

Check each character to see if it is in the range ASCII A 
to ASCII Z. If so, convert to lowercase by adding 32(10) 
= 40(8) to that value, or else continue. 

Write out the buffer BUFF, which has the converted 
message. This is a Write Virtual Block. We use the $S 
form instead of the $C form because we don't know how many 
characters to write until run time. The $ form would also 
work. Notice the difference in the format of the 
arguments for the $S form compared to the $C form. Note 
also that in the $S form, the lack of a '#' sign in IOSB + 
2 means get the contents of that location, specifically 
the number of characters to write out. The third argument 
of the I/O parameter list, #40, is for vertical format 
control. Single linefeed before writing the characters is 
indicated by #40, or ASCII space. 

Check for any directive or I/O errors. 

See note 4. R5 is the directive counter, which will be 
one for the first QIO and two for the second QIO. We need 
to distinguish directive errors from I/O errors. In this 
example, we use R4 to distinguish the two type of errors. 
Zero in R4 means a directive error, and -1 (or 177777(8) 
in two's complement) in R4 indicates an I/O error. For 
directive errors, the DSW is placed in R3; for I/O 
errors, the I/O status byte is placed in R3. 
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The list of all error codes appears in Appendix B of the 
RSX-11M/M-PLUS I/O Drivers Reference Manual and in the RSX-11M 
Mini-Reference Manual . Of course, this simple error handling will 
normally be replaced with a text error message and the error code. 
You will learn how this is done later in the module. 

NOTE 

Although both virtual block and logical block 
operations are permitted to a terminal, it is 
safer to use virtual block operations. If 
the I/O is actually performed at a terminal, 
the virtual block request gets converted by 
the Executive to a logical block request. 
If, for example, logical block writes are 
used and someone reassigns the LUN to a disk, 
the write may overwrite a block on the disk. 
If, on the other hand, write virtual blocks 
are used and someone reassigns the LUN to a 
disk, the write will only be allowed if a 
file is open on the disk. The write will 
fail in most cases if the program is writing 
to a terminal. 
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1 

2 
3 
4 
5 
6 
7 
8 
9 
10 
il 

13 

O 15 
016 

17 
18 

1? 

20 
21 
22 
2.3 

24 

25 

26 

•[s 

2? 

30 
31 
32 
^33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
.44 
45 
46 
47 



© 



♦TITLE SYNCHQ 
♦ I DENT /01/ 
♦ENABL LC 



r Enable lower case 



i + 

9 



FILE SYNCHQ ♦ MAC 



This task reads a line of text from the terminal? 
converts all upper case characters to lower case? 
prints the converted message back at the terminal 
uses synchronous QIO directives* 



and 
1 1 



♦ MCALL QI0W*C*QI0W*SrEXIT*S ? 



External 
mac ros 



system 



iosb: 

BUFF t 

start: 



♦ BLKW 

♦ BLKB 

CLR 
CLR 



80* 

R5 
R4 



QI0W*C I0»RUB?5yl 



loop: 



BCS 
TSTB 
BLT 
MOV 

CLR 

CMPB 



BLT 

CMPB 

BGT 

9 Here if upper 
MOVB 
ADD 
M0VB 

next: INC 

SOB 

QI0W*S 



ERR1 
IOSB 
ERR1A 
I0SB+2?R0 

Rl 

BUFF < Rl ) ?* 
NEXT 

BUFF(Rl) y* 
NEXT 

case? move 
BUFF(Rl) tR 
#32* fR2 
R2? BUFFCRl 
Rl 

ROyLOOP 
#I0»WVBj»#5! 



9 I/O Status Block 
9 Text buffer 

9 Error Count 
9 Error indicator ~ 
9 means d i r e c t i v e e r r o r 
9 <DSW in R3) 9 ne?.f 
9 means I/O error 
9 (I/O status in R3) 
9 9 IOSB? 9 <BUFF 9 80 ♦ > ? Issue 

9 read 
f Branch on dir error 
9 Check for I/O error 
.5 Branch on I/O error 
9 Get count of characters 
9 typed in 

9 Offset into buffer to 
9 character 
"A 9 Check for upper case 
9 ASCII character 
9 Branch if below range 



'Z 



9 Branch if above range 
to register R2 and convert 
2 9 Move to register 

9 Convert to lower case 
) 9 Replace in message 

9 Increment offset into 
9 buffer to next char 
i Decrement count of 
i characters left to check 
*lt >#I0SB> ?<#BUFFyI0SB+2y*4O> 
9 Write text 



Example 3-1 Synchronous 1/0 (Sheet 1 of ?) 
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"48 
49 
.50 
51 
52 
53 
54 
"55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
"68 
69 



BCS 

TSTB 

BLT 

EXIT*S 

9 

i Error code 
f 

ERR2AJ INC 
ERR 1 A J INC 
M0VB 

DEC 

IQT 



ERR2 J 
ERR1 i 



INC 
INC 
MOV 



ERR2 
IOSB 
ERR2A 



R5 
R5 

I0SB»R3 



R4 



R5 
R5 

$DSWmR3 



IOT 

♦END START 



? Branch on dir error 

> Check for I/O error 

9 Branch on I/O error 

9 Exit 



9 Up error count - 2nd QIO 
9 - 1st QIO 

I/O error* I/O status 

to R3* 
Negative value in R4 

means I/O error 
Trap and display 

registers 
Up error count - 2nd QIO 
- 1st QIO 
Directive error* DSW 

to R3» leave R4~0* 
Trap and display 
registers 



Run Session 
>RUN SYNCHQ 

ABCDEFGHl'JkliTinop«rstuvw>{y2l2345678C3\ 
abcdef sfh i Jk 1 mnopa rst u vwxys 12345678C 3 \ 



Example 3-1 Synchronous I/O (Sheet 2 of 2) 
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Asynchronous I/O 

The format of the QIO$ call is: 

QIO$ i f n , lun , efn , pr i , iosb, ast , iopl 

where 

ifn - I/O function code 

lun - Logical unit number 

efn - Event flag number 

pri - Priority (not used) 

iosb - I/O status block address 

ast - AST routine address 

iopl - I/O parameter list (up to six words) 
Example using the $C form: 
. MCALL QIO$C 



IBUF: .BLKB 80. 
IOSB: . BLKW 2. 



QIO$C I0.RVB,5,1, , IOSB , ,<IBUF,80.> 



Explanation of QIO arguments: 

Read Virtual Block 

LUN 5 (TI:) 

Event flag 1 

Priority (ignored) 

I/O status block address = IOSB 

AST routine address (not used here) 

I/O parameter list 

Buffer address = IBUF 

Buffer length = 80. 



Ill 



USING THE QIO DIRECTIVE 



Synchronization With Asynchronous I/O 

As mentioned earlier, event flags and asynchronous system 
traps may be used for synchronization. If an event flag is 
specified, the Executive clears the event flag when the I/O packet 
is queued and sets the flag again when the I/O transfer completes. 
This happens with both synchronous and asynchronous I/O, if an 
event flag is specified. With asynchronous I/O, the task can 
specify a flag and use it for synchronization using one of the 
following techniques. 

1. Do some work, then wait for the flag to be set. 

2. Work the entire time, periodically checking the flag until 
it is set. 

Another possible technique for synchronization is to use ASTs 
(discussed in Chapter 2) . The following techniques might be used 
with ASTs, after specifying an AST routine address in the QIO$ 
directive. 

1. "Main" task does some work, then suspends or stops itself. 
AST routine resumes or unstops the task. 

2. "Main" task works the entire time, periodically checking a 
cleared event flag or a cleared byte in a local data area. 
AST routine sets the flag or sets the byte to a nonzero 
value, thus notifying the "main" task that the I/O 
operation has completed. If an event flag is used, it 
will typically be different from the flag specified in the 
asynchronous I/O request. 

A third technique which can be used is to monitor the 
contents of the I/O status byte of the I/O status block. The 
complete I/O status block is cleared when the I/O request is 
queued to the driver. Later, it is filled in when the I/O 
transfer completes. Therefore, the user task can periodically 
check the contents of the I/O status byte for a nonzero value. 
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Example 3-2 demonstrates the use of asynchronous I/O to 
perform the same function performed in Example 3-1. This task can 
do some work in parallel with the I/O transfer. The following 
notes are keyed to the example. 

O Here we use QIO$C and QIO$S instead of QIOW$C and QIOW$S. 
WTSE$C is a Wait for Single Event Flag directive, used to 
synchronize the I/O operation. 

Q A work buffer to be filled with values while the I/O 
transfer is going on. 

Issue the read. QIO$C instead of QIOW$C. All arguments 
are the same. If ASTs were used for synchronization, an 
AST address would be specified. The Executive will clear 
Event Flag 1 when the I/O packet is queued and set it when 
the I/O operation completes. 

Q Check again immediately for directive errors. Here, you 
are checking for an error in queueing the I/O packet. 

Q While the I/O transfer itself takes place, you can do some 
work. Here fill the "array" at K with the values 64., 
128. , . . . , 640. 

O When you are finished with your work, enter a Wait For 
state until the event flag specified in the QIO$ directive 
is set. It will be set when the I/O operation completes. 

O Now that the I/O operation is finished, check for I/O 
errors . 

Q After converting the message, issue the write. 

Q This time, wait for the flag to be set immediately after 
checking the directive status. You could do some more 
work here. If you choose to wait, it is simpler and more 
efficient to use synchronous I/O (QIOW$). Synchronous I/O 
is more efficient because you perform both functions (QIO$ 
and WTSE$) in just one Executive directive call. 

© Still use the error count to indicate the directive 
number. Since there are now extra directives (the WTSEs) , 
adjust the counts accordingly. 
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3 
4 
5 
6 
7 
(3 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
"28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
"38 
39 
40 
41 
42 
43 
"44 
45 
46 
47 



♦TITLE ASYNCQ 
♦I DENT /01/ 
♦ENABL LC 

ILE ASYNCCKMAC 



y Enable lower case 



This task reads a line of text from the terminal? 
converts all upper case characters to lower case? and 
prints the converted message back at the terminal* It 
uses asynchronous QlOy usinsf wait for event flag for 
synchronisation ♦ 



iosb: 
buff: 
k: 



start: 



♦ MCALL 



♦ BLKW 

♦ BLKB 

♦ BLKW 



CLR 
CLR 



G:i:0*C»aiO*SyEXIT$SyWTSE*C y External 
? system macros 



80* 
10* 



R5 
R4 



QI0*C 
BCS 

y Now do some 
CLR 
MOM 

PLACE * MOV 
ADD 

CMP 
BHI 
ADD 
BR 



lO.RVBySyly y IOSB 

ERR1 
work 
RO 

#64* yRl 
RlyK'(RO) 
#2 y RO 

R0y*20. 
WAIT 
#64 ♦ y Rl 
PLACE 



y Now wait for I/O operation 

wait: wtsesc i 



to 



BCS 
TSTB 
BLT 
MOV 

CLR 



ERR2 
IOSB 
ERR1A 
I0SB+2yR0 

Rl 



I/O Status Block 
Text buffer 
Array to fill while 
waiting for I/O 

Error Count 

Error indicator* 
means directive errory 
~1 means I/O error 
y<BUFFy80* y40> y Issue 
read 

Branch on dir error 

Offset into array K 
Value to place in array 
value in array 
to n e x t e 1 e m e n t 



Place 
Point 
in K 
At the end? 
Branch if done 
Compute next value 
Place it in the array 
complete 

Wait for I/O to 

complete 
Check for dir error 
Check for I/O error 
Branch on I/O error 
Get count of character* 

typed in 
Offset into buffer to 
character 



Example 3-2 Asynchronous I/O Using Event Flags 
for Synchronization (Sheet 1 of 2) 
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48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
"79 
80 
81 
82 
83 
84 
.85 
86 
87 



LOOP ♦ 



CMPB 



BLT 

CMPB 

BGT 

r Here if upper 
MOVB 
ADD 
MOVB 

next: INC 

SOB 
QIO*S 

BCS 

y Could do some 
WTSE*C 

BCS 

TSTB 

BLT 

EXIT*S 
? Error code 
ERR3AJ INC 

INC 

ERR1 A * INC 
DEC 



MOVB 
IOT 

INC 
INC 
INC 
INC 
MOV 



ERR4 : 
ERR3 ♦ 
ERR2 ♦ 
ERR1 1 



BUFF(Rl) y#'A 
NEXT 

BUFF(Rl) y*'Z 
NEXT 

cssey move to 
BUFF(Rl) yR2 
#32* yR2 
R2yBUFF(Rl ) 
Rl 

ROyLOOP 
#I0*WVBy#5y#ly 

ERR3 

more work here 
1 

ERR4 
I0SB 
ERR3A 



R5 
R5 
R5 
R4 

I0SByR3 



R5 
R5 
R5 
R5 

$DSWyR3 



y Check for upper case 

y ASCII character 

y Branch if below range 

? Branch if 3bove range 
register R2 and convert 
y Move to register 
y Convert to lower case 
y Replace in message 
y Increment offset into 
y buffer to next char 
y Decrement char count 
y *I0SBy y <#BUFFyI0SB+2y#40:: 
y Write text 
y Branch on dir error 
too 

y Wait for I/O to 
y complete 
y Branch on dir error 
y Check for I/O error 
y Branch on I/O error 
y Exit 

y R5=3y 2nd QIO 



IOT 

♦END START 



R5=ly 1st QIO 

Make R4 negative to 

indicate I/O error 
I/O status to R3 
Trap and display 

registers 
R5~4y 2nd Wait For 
R5~3y 2nd QIO 
R5=2y 1st Wait For 
R5=ly 1st QIO 
Directive error* DSW 

to R3y leave R4~0* 
Trap and display 

registers 



Run Session 
>RUN ASYNCQ 

3bcdefghKJHKJHKHFRTEWawryuyiupoZCVcvbvcnbMBNM7< 8534243" t ' 
abcdef ghk JhkJhkhf rtewawryuy iupo£cvcvbvcnhmbnm7 (8534243 " ♦ ' 



Example 3-2 Asynchronous 
for Synchronization 



I/O Using Event Flags 
(Sheet 2 of 2) 
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Example 3-3 shows the use of ASTs for synchronization. In 
addition, it shows the use of some supplied macros for generating 
error reports. These macros are documented in Appendix A of this 
course. The following notes are keyed to the example. 

O This is the text for the messages to be written. The 
LEN=.-MES lets the assembler calculate the length of the 
message for you. A similar technique is used for the 
other messages. 

Q The ASCII text may contain an odd number of characters. 
The .EVEN assembler directive assures that your first 
executable instruction is an even word boundary. 

O Issue the write request. The AST routine address is 
specified. Also specify the address of the buffer, MES, 
and its length LEN. You can use the $C form of the 
directive because all arguments are known at assembly 
time . 

Q Suspend until the AST routine is activated^ upon I/O 
completion. Normally some other processing would be done 
here, in parallel with the I/O operation. 

O Tne Executive passes control to the AST routine when the 
I/O transfer completes. First check the I/O status. You 
do that here instead of in the main code because you will 
be issuing another write which will overwrite the IOSB. 
The I/O status check could otherwise be checked in the 
main code after the task is resumed. 

O Write out a message so the operator knows you are in the 
AST routine. This time you use synchronous I/O, since you 
aren't planning to do any work while the I/O transfer 
takes place. Again, check for errors. 

Q Resume the task so it will be ready to run upon exit from 
the AST routine. 

O Po P tne extra word off the stack (this AST is entered with 
five words on the stack instead of the standard four) . 
Then use the ASTX$ directive to exit the AST routine via 
the Executive. 

Q Check for directive errors on the SPND$. It's possible 
that you never suspended yourself. 



116 



USING THE QIO DIRECTIVE 



Write another message synchronously, check for errors, and 
then exit. 

The DIRERR and IOERR macros generate error messages for 
you. DIRERR generates a message with the following 
format . 

DIRECTIVE ERROR 
<user message> 

DSW = <value> (in signed decimal) 



IOERR generates a message of the following format: 

I/O ERROR 
<user message> 

I/O STATUS BLOCK = <hb> , <lb>/<2nd word> 
(in signed decimal) 

hb is the high byte of the first word, 
lb is the low byte of the first word. 



Each of these macros then causes the task to exit. Later 
in this module you will learn how to generate such 
messages yourself. 
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1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 

©31 
Q32 

33 
34 

© 35 
Q36 

© 37 

38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
L48 



♦ TITLE QIOAST 
♦ I DENT /Ol/ 
♦ENABL LC 



r Eri3ble lower case 



FILE QIOAST^MAC 



This program issues 3 QIO and then suspends itself* 
When the I/O operation completes* an AST routine is 
invoked which resumes the task* 

Assemble 3nd task-build instructions* 

MACRO/LIST LB! CI f 13PR06MACS/LIBRARY»dev:Cufd3QI0ASR 
LINK/MAP QIOAST y LB: CI ylZIPROGSUBS/LIBRARY 

Install and run instructions* Install the task so that 
the Resume directive works properly* 



iosb: 

MESI 
LEN 

mesi: 

LEN1 
MES3* 

LEN3 

start: 



r Main 

erri: 
erria: 

ERR2: 
ERR3: 
ERR3A : 



♦ MCALL 
♦MCALL 
♦MCALL 

♦ BLKW 
♦ASCII 

♦ASCII 
♦ASCII 

♦ASCII 
♦ASCII 

♦ EVEN 
QI0*C 

BCS 

SPND*S 

BCS 

QI0W*C 

BCS 

TSTB 

BLT 

EXIT*S 
code er 
DIRERR 
I0ERR 
BIRERR 
BIRERR 
I0ERR 



EXIT$SyQIO$CyQIOW*CyASTX$S 5 System 
SPNDfS yRSUMSC y macros 

lOERRyBIRERR r Supplied macros 
2 5 I/O status block 

/"QIOAST ' IS STARTING/ y Startup message 
♦ ~MES 

/'QIOAST' HAS BEEN RESUMED AND WILL/ 
/ NOW EXIT/ ? Resumed message 

♦ —MESI 

/ASTRT IS EXECUTING AND WILL NOW/ 
/ RESUME QIOAST/ y AST message 
♦ -MES3 



10 ♦ WVB y 5 y 1 y y I OSB y ASTRT y <MES y LEN t 40> 
y Issue write 
y Branch on dir error 
? Suspend self 
y Branch on dir error 
5 y 1 y y IOSB y y <MES1 r LEN1 y 40> y Issue 
y write 

y Branch on dir error 
y Check for I/O error 
y Branch on I/O error 
y Exit 
sins supplied macros 
BY QI0AST> 
ST QIO BY QI0AST> 



ERRI 

ERR2 
I0*WVBy 

ERR3 
IOSB 
ERR3A 



ror handl 
<ERR0R 
#I0SBy< 
< ERR OR 
<ERR0R 
#I0SBy< 



mgy u 
ON 1ST 
ERROR 
ON SUS 
ON 2ND 
ERROR 



QIO 
ON 1 
PEND 

QIO 
ON 



BY QIOAST.:- 
ND QIO BY QI0AST> 



Example 3-3 Asynchronous I/O Using an AST for Synchronization 
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e 

e 



49 
50 
51 
52 
"53 
» 54 
.55 
56 
57 
58 
59 
60 
61 
62 
'63 
64 
L65 
66 
67 
'68 
69 
.70 
71 



AST service routine ••- entered when the 1st QIO by the* 
main code completes 



ASTRT i TSTB 
BLT 

QI0W*C 

BCS 
TSTB 
BLT 

RSUM*C 

BCS 
TST 

ASTX*S 



5 AST 
ERR 4: 
ERR4A 

errs: 



check I/O status on 

I/O operation 
Branch on I/O error 
><MES3j>LEN3»40> r Issue 

write 
Branch on dir error 
Check for I/O error 
Branch on I/O error 
Resume task 
Branch on dir error 
Pop AST specific word 

off stack 
Leave AST state and 
return to main code 
error handling code 

DIRERR <ERR0R ON QIO BY AST ROUTINE.'?- 
IOERR *10SBy<ERR0R ON QIO BY AST ROUTINE.'?- 
DIRERR <ERR0R ON RESUME BY AST ROUTINE!?- 
♦END START 



IOSB 
ERR1A 

IQ»Wv-B*5yly?I0SB 

ERR4 
IOSB 
ERR4A 
Q I OAST 
ERRS 
(SP) + 



Run Session 

.-•INSTALL QIOAST 
>RUN QIOAST 

' QIOAST ' IS STARTING 
AST IS EXECUTING AND WILL NOW RESUME QIOAST 
'QIOAST ' HAS BEEN RESUMED 



Example 3-3 Asynchronous I/O Using an AST for Synchronization 

(Sheet 2 of 2) 
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TERMINAL I/O 



Device Specific Functions 

Some device-specific function codes are listed in Table 3-3. 
Table 2-3 in section 2.3 (on the QIO macro) of the RSX-11M/M-PLUS 
I/O Drivers Reference Manual lists all of the available special 
functions for the full-duplex terminal driver. As noted, some of 
these functions are SYSGEN options. 

Many of the device-specific functions are selected using 
subfunction bits. These bits may be ORed with standard or 
device-specific function codes to produce special functions. 
Table 2-4 in Chapter 2 of the I/O Driver's Reference Manual lists 
the various combinations which are possible. For example, TF.TMO 
(read with timeout) ORed with a read function (IO.RLB, 10. RPR, 
IO.RNE, etc.) terminates the read if the specified time period 
goes by between keystrokes. Notice that some device-specific 
functions, such as Read No Echo (IO.RNE), have equivalents using 
subfunction bits (IO.RLB! TF.RNE) . Read After Prompt (10. RPR) on 
the other hand, has no equivalent using subfunction bits. 

NOTE 

When you OR subfunction bits with read or 
write functions, use Read Logical Block or 
Write Logical Block, not the Read Virtual 
Block or Write Virtual Block. If the 
Executive converts a virtual block operation 
to a logical block operation, any subfunction 
bit settings are lost. 

For additional information on the device-specific function 
codes, see section 2.3.2 on Device-Specific Functions in the 
RSX-11M/M-PLUS I/O Drivers Reference Manual . Examples of the use 
of Read After Prompt, Read No Echo, and Read With Timeout are 
included here. 



I/O Status Block and Terminating Characters 

As for other I/O functions, the low order byte of the first 
word of the I/O status block contains the I/O status byte, 
indicating the success or failure of the I/O operation. Also, the 
second word contains the count of characters actually transferred. 
For reads from a terminal, the high order byte of the first word 
of the I/O status block contains the terminating character in 
ASCII (<RET>, CTRL/C, etc.) for successful reads. 
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Normally, CTRL/Z is treated as an error. The I/O status byte 
is set to IE. EOF (-10.) and the character count contains the count 
of characters read before the CTRL/Z. Example 3-4 shows how 
CTRL/Z can be specially handled in a program. Two special 
function codes, IO.RST and IO.RTT, allow reads to be successfully 
terminated by nonstandard terminating characters. The first 
allows any non-alphanumeric character to terminate input; the 
second allows the user to specify which character or characters 
should terminate the read. 
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Table 3-3 Some Special Terminal Function Codes 



Global 
Symbol 

IO.RNE 



10. RPR 
IO.RST 

IO.RTT 
IO.WBT 



Octal 
Value 

001020 
004400 
001001 

005001 
000500 



None 



001200 



Function 

Read With No Echo 
(Same as 10. RLB ! TF.RNE) 

Read After Prompt 



Read With Any 
Special Terminators 
(Same as IO.RLBITF.RST) 

Read With Specified 
Special Terminators 

Write Logical Block, 
through ongoing I/O 
(Same as IO.WLB • TF.WBT) 
Task must be privileged 

Read With Timeout 
(10. RLB! TF.TMO) 



I/O Parameter 
<stadr , si ze [ , tmo] > 



<stadr , size , [ tmo] , 
pradr,prsize ,vf c> 

<stadr , si ze [ , tmo] > 



<s tadr , si ze , [ tmo] , 
table> 

<stadr , size ,vfc> 



<stadr , si ze , tmo> 
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Read After Prompt 

The Read After Prompt function allows the combination of a 
write of prompting text followed by a read in a single QIO 
request. System overhead is lower because only one QIO directive 
is processed. In addition, there is no window during which a 
response to the prompt may be ignored. Such a window may occur if 
separate QIOs are used to write and read, and if there is a delay 
between the write of the prompt and the read. The I/O parameter 
list contains six parameters, three for the read, and three for 
the write. The following notes are keyed to Example 3-4. 

O Placing the buffer with "You typed:" just ahead of the 
buffer for the input text allows the use of a single QIO 
to write out the complete line of output text. FINMES is 
the starting addres of the output text and length is FLEN 
+ n, where n is the number of characters typed in. 

Q We assign the symbol IOLEN to the second word of the IOSB. 
This allows you to reference that word with IOLEN, instead 
of using IOSTAT + 2. 

O QIO for Read After Prompt. The function code is 10. RPR. 
The first three parameters in the I/O Parameter List are 
for the read, the last three are for the write. The write 
is performed first, followed by the read. The 44(8) for 
the vertical format control causes the prompt text to 
appear on the next line, followed immediately on the same 
line by the prompt for the read. 

O We are going to display the message typed, preceded by the 
text "you typed in." By placing the input buffer BUFF 
immediately after the preceding text, we now have our 
output text as one string beginning at FINMES. The total 
length of the message to be displayed is the length of the 
preceding text plus the number of characters typed in. 

O Use a normal QIO with Write Virtual Block to display the 
output. 

O If tne operator types a CTRL/Z, an error status is 
returned. In this case, simply exit normally. Therefore, 
you must check for this condition and handle it specially. 



123 



USING THE QIO DIRECTIVE 



3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 



♦TITLE 
♦ IDENT 
♦ENABL 



PROMPT 
/Ol/ 
LC 



r Enable lower case 



i File PROMPT ♦ MAC 



9 This task prompts the user for an input string and 

r then echos the string to the terminal* It repeats this 

? process until the user types a CTRL/Z* 

? 

5 Assemble and task-build instructions* 



prom: 

PL EN 
F.TNMES * 
FLEN 
BUFF* 

I0STAT* 



MACRO/LIST LB: CI* 1 3PR0GMACS/LIBRARY y dev : CuicIIPROMPT 
L I NK/MAP PROMPT y LB : C 1 y 1 3PR0GSUBS/L IBRARY 



♦ MCALL 
♦MCALL 

♦ASCII 

♦ASCII 

♦ BLKB 

♦ EVEN 

♦ BLK'W 



EXIT*SyQIOW*S 
BIRERR i I0ERR 



5 System macros 
y Supplied macros 



/Please 
♦ -PROM 
/You typed: 
♦-FINMES 
80* 

1 



iolen: ♦blkw 



start: qiow*s 



BCS 
TSTB 
BLT 
ADD 



BCS 
TSTB 
BLT 
BR 

> Errors come 



type anything: / J Prompt 

9 Length of prompt 

$ Echo prefix 

9 Length of above 

9 Buffer 

9 Move to word boundary 

9 I/O status block for 
$ QIOs* 

1 9 2nd word of I/O status 

9 block 

#I0*RPRy#5y#ly ytflOSTATy y<#BUFFy#80» 9 y#PR0My#PLENy#44 

9 issue QIO for Read 

9 After Prompt 

y Branch on dir error 

9 Check I/O status 

9 Branch on I/O error 

r Add length of prefix 
9 to that of entered text 
9 #1 OSTAT 9 9 <#FINMES 9 IOLEN y #40> 

9 Write the new messege 

i Branch on dir error 

9 Check for I/O error 

9 Branch on I/O error 

9 Start over again 



DERR 
I0STAT 
I ERR 

tFLENy I0LEN 



QI0W*S #I0,WVBy#5y#l 



CERR 
I0STAT 
OERR 
START 
here 



DERR : 

cerr: 
i err: 



jerr : 



OERR : 



DIRERR (Error in QIO to 



READ 
Use 



AFTER 
macro 



PR0MPT> 
to tell 



of 



DIRERR 

CMPB 

BNE 

EXIT$S 
I OERR 



I OERR 
♦ END 



•(Error in QIO to WRITE> 

#IE ♦ EOF 9 10STAT 

JERR 



dir error 
Check for ~Z 
Branch if not* 
9 was I/O error 
9 Normal exit 
*IOSTATy<Error in READ AFTER PR0MPT> 

J Use macro to 
9 tell of 
#IOSTATy<Error in WRITE> ? I/O error 
START 



Example 3-4 Prompting for Input (Sheet 1 of 2) 
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Run Session 
>RUN PROMPT 

Please type anything* sJkshJHGJHGHFY134435 
You typed* sJkshJHGJHGHFY 134435 
Please type anything* hello there 
You typed* hello there 
Please type anything? ~Z 



Example 3-4 Prompting for Input (Sheet 2 of 2) 
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Read No Echo 

Read No Echo is used to override the default of echoing each 
character as it is typed. This is used for passwords and other 
private information. Example 3-5 uses this function. The 
following notes are keyed to the example. 

Q The .NLIST BEX assembler directive instructs the assembler 
not to list binary code which takes up more than one line. 
This saves room in the listing for all the ASCII text. 
Return to listing binary extensions for the code by using 
a .LIST BEX assembler directive. 

O As i n tne previous example, we display the text typed in, 
preceded by our own message. Since the Read No Echo 
doesn't echo any characters back and thus doesn't move the 
cursor on the screen at all, precede the text with a 
carriage return (15(8)) to get the cursor back to the 
start of the line. If this is not done, the NO LONGER A 
SECRET WORD message will begin away from the left hand 
margin, below the : in "SECRET WORD". 

Q Write prompting text, then leave cursor at that position 
for input (since 44(8) is used for vertical format 
control) . 

Q Read No Echo QIO. Standard read parameters except for the 
function code. 

Q As in the previous example, add the length of the 
preceding text to the text typed in to determine the total 
length of the output message. Here, however, you do the 
calculation in a register instead of in the IOSB. Since 
the Read No Echo doesn't echo any characters back, it 
doesn't move the cursor on the screen. Therefore, precede 
the text with a carriage return (15(8)) to move the cursor 
back to the start of the line. Without it, the "NO LONGER 
A SECRET WORD" message will begin away from the margin, 
below and after "SECRET WORD: ". 

You can combine the write of the prompt and the read into one 
QIO directive call using a Read After Prompt with the Read No Echo 
subfunction bit (10. RPR! TF.RNE) . If you want, imbed the carriage 
control characters in the message. 
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6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
2? 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 



♦TITLE NOECHO 
♦ I DENT /Ol/ 
♦ENABL LC 



r En3ble lower esse 



y-f 

y FILE NOECHO* MAC 



? This task prompts for input y reads it without echoy 

y displays the input text 3nd exits* 

y 

f Assemble and task-build instructions* 
r 

5 MACRO/LIST LB JO * 1 3PR0GMACS/LIBRARY y dev ♦ CuicHNOECHO 

5 LINK/MAP NGECHOy PROGSfUBS/LIBRARY 



MESJ 

LEN 

BUFFI 

BLEN 
BUF t 

iosb: 
lent: 



♦MCALL 
♦MCALL 
*NLIST 

♦ASCII 

♦ASCII 



♦ BLKB 

♦ EVEN 

♦ WORD 

♦ WORD 



EXIT$SyQIOW$CyQIOW*S y System macros 
DIRERR 
BEX 



I0ERR 



/SECRET 
♦ — MES 
<15>/N0 

♦-BUFF 
80* 






♦LIST BEX 



y Supplied macros 

r Don't list binary 

$ extensions 

WORD* / y Prompt messege 

y Length of prompt 
LONGER A SECRET WORD* / 

? Preceding remark 

y Length of Remark 

5 Input buffer 

y Word align for IOSB 

y IOSB is broken into 

y two parts for 

y convenience* 

y List binary extensions 



START* QI0W*C I0*WVBy5y 1 y y IOSB? y <MES y LEN y 44.': 

y prompt 
DERR1 y Branch on 

IOSB y Check for 

IERR1 y Branch on 

1 ♦ RNE y 5 y 1 y y I OSB y y <BUF y 80 ♦ > 



y Write 



y l-rro 
IERR1 ♦ 
IERR2 * 
I ERR 3 ♦ 
DERR1 : 
DERR2* 
DERR3* 



BCS 
TSTB 
BLT 

QI0W*C 
BCS 
TSTB 
BLT 
MOV 
ADD 

QI0W*S 

BCS 

TSTB 

BLT 

EXIT*S 
rs come 
l'OERR 
I0ERR 
I0ERR 
DIRERR 
DIRERR 
DIRERR 
♦ END 



DERR2 

IOSB 

IERR2 

LENTyRO 

♦BLENyRO 



y Branch on 

y Check for I/O 

y Branch on I/O 

y Get length of 

y Add length of 



dir error 
I/O error 
I/O error 
y Read Noecho 
dir error 
error 
error 
input 
remark 



#I0*WVBy#5y#ly y#I0SBy y <#BUFF y RO y #40> 



DERR3 
IOSB 
I ERR 3 

here 

#IOSBy<Error on 
#IOSBy<Error on 
#IOSBy<Error on : 
•(Error in QIO on 
•(Error in QIO on 
<Error in QIO on 
START 



y Write out 
5 Branch on 
9 Check for 
y Branch on 
? Exit 

1st WRITE> i 
READ> i 
2nd WRITE> 
1st WRITER- 
READ;* 

2nd WRITE> 



text 

dir error 
I/O error 
I/O error 



Display I/O 
message and 
exit 

Display dir 
message and 
exit 



Example 3-5 Read No Echo (Sheet 1 of 2) 
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Run Session 

>RUN NOECHO 
SECRET WORD: 

NO LONGER A SECRET WORD* ADD 



Example 3-5 Read Mo Echo (Sheet 2 of 2) 



Read with Timeout 

Example 3-6 is a repeat of Example 3-1, only with a timeout 
on the read. The following notes are keyed to the example. 

O To invoke the timeout mechanism, TF.TMO is ORed with the 
read function (IO.RLB) . You must use Read Logical Block 
here, because any subfunction bits are stripped off when a 
Read Virtual Block is translated to a Read Logical Block 
function. In addition, the third parameter in the I/O 
parameter list specifies the length of the timeout in 10 
second intervals. This timeout occurs if that amount of 
time passes between successive keystrokes. If a timeout 
occurs, input is terminated, but no error is reported. 
Instead, the success code +2 is returned rather than the 
standard +1. 

Q On the Run Session - In the first run, the QIO timed out 
after KJHKJjjj. In the second run, the QIO was terminated 
with a carriage return before it timed out. 

To handle the timeout specially, just check the I/O status 
byte for a value of +2 (IS.TMO) . Another alternative for placing 
a time limit is to use a Mark Time directive (MRKT$). The timeout 
with a Mark Time is for the entire input, rather than for the next 
keystroke . 
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1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 



♦TITLE QIQTIM 
♦ I DENT /Ol/ 
♦ENABL LC 



f Enable lower case 



? FILE QIOTIM*MAC 



This task reads a line of text from the terminal* 
converts all upper case characters to lower case? and 
prints the converted message back at the terminal* It 
uses synchronous QIQsy with a timeout on the read* 



♦MCALL QI0W*C»QI0W*SfEXIT*S 9 System macros 



I0SBJ 

buff: 



♦ BLKW 

♦ BLKB 



80* 



start: clr rs 

CLR R4 



QI0W*C I0*RLB!TF»TM0> 

BCS ERR1 

TSTB I0SB 

BLT ERR1A 

MOV I0SB+2>R0 

CLR Rl 

LOOP: CMPB BUFF(Rl)y#'A 

BLT NEXT 

CMPB BUFF(R1>>#'Z 

BGT NEXT 

r It is upper case* so move to 

MOVB BUFF(Rl) rR2 

ADD #32.»R2 

MOVB R2»BUFF<R1> 

next: INC Rl 

SOB R0»L00P 

QI0W*S #I0*WVBf *5y#ly 

BCS ERR2 



t I/O Status Block 

J Text buffer 

9 Error Count 

5 Error indicator - 

y means directive error? 

i (DSW in R3)y ne.g means 

9 I/O error (I/O status 

i in R3) 
5 9 1 9 9 1 OSB 9 9 <BUFF 9 80 ♦ y 1 > 

9 Issue read 

9 Branch on dir error 

9 Check for I/O error 

i Branch on I/O error 

i Get count of characters 

9 typed in 

i Offset into buffer to 

9 character 

9 Check for upper case 

9 ASCII character 

i Branch if below range 

9 Branch if above range 
register R2 and convert 

9 Move to register 

9 Convert to lower case 

i Replace in message 

9 Increment offset into 

9 buffer to next char 

9 Decrement count of 

9 characters left 
9 #1 OSB 9 9 <#BUFF 9 IOSB+2 9 *40> 

f Branch on dir error 



Example 3-6 Read With Timeout (Sheet 1 of 2) 
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48 




TSTB 


IOSB 


r Check for I/O error 


49 




BLT 


ERR2A 


r Branch on I/O error 


50 




EXIT$S 




51 


9 








52 


r Error 


code 






53 


r 








54 


ERR2A : 


INC 


R5 


r R5=2y 2nd QIO 


55 


erria: 


INC 


R5 


? R5~l» 1st QIO 


56 




MOVB 


IOSB* R3 


9 I/O error* I/O status to R4» 


57 




DEC 


R4 


9 Negative value in R4 


58 








9 means I/O error 


59 




I0T 




9 Trap and display registers 


60 


ERR2 * 


INC 


R5 


9 R5=2> 2nd QIO 


61 


ERR1 : 


INC 


R5 


9 R5=l 9 1st QIO 


62 




MOV 


$DSW,R3 


9 Directive error* DSW 


63 








9 to R3» leave R4=0» 


64 




I0T 




9 Trap and display registers 


65 




♦ END 


START 





Run Session 

">RUN QIOTIM 
KJHKJJJJ 

k JhkJJJJ 
>RUN QIOTIM 
J J J a f h k J f i u r < R E T > 
_ JJJsf hkJf iur 



Example 3-6 Read With Timeout (Sheet 2 of 2) 
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Terminal-Independent Cursor Control 

Terminal-independent cursor control is a SYSGEN option, 
provided only if selected. If it is selected, certain I/O 
requests are automatically converted by the terminal driver for 
the specific device for which the I/O request is made. This is 
typically done with escape sequences used for positioning the 
cursor. This allows a task to move the cursor to any position on 
the screen and then write a message. 

This can also of course be done by imbedding the terminal 

specific escape sequences into the write buffer. However, the 

advantage of using terminal-independent cursor control, is that 

the same program will work at different terminals (VT-52*s and 

VT-100's, for example), without any need for modification. 

All you need to do is place the proper value in the vertical 
forms control word of the I/O parameter list. If the high order 
byte is non-zero, then the word is interpreted as a cursor 
position. The high order byte is the line number, and the low 
order byte is the column number. Home position, the upper left 
corner of the screen, is defined as line 1, column 1. 

To start the display at line 10., column 25., place a 10. in 
the high order byte and a 25. in the low order byte. An easy way 
to do this is to let the assembler convert 10.*256.!25. for you. 
In general, X*256.!Y corresponds to position X,Y on the screen. 
In addition, if bit 15 (the most significant bit in the line 
number byte) is set, the screen is cleared before the cursor is 
moved . 

Example 3-7 demonstrates the use of terminal-independent 
cursor control. The following notes are keyed to the example. 

O Parameters defined with symbols so that they can easily be 
changed. 

O Use the $ form of the mark time directive to allow reuse 
of a single DPB. 

O Issue a mark time directive for one minute to set event 
flag 3, allowing the task to exit after one minute. 
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Modify the DPB and use it over and over again, at line 34, 
to mark time for Z seconds before updating the display. 
The second mark time uses event flag 2, to avoid 
conflicts. This approach saves task space since the DPB 
is used again. 

Issue the Z second mark time directive. We will wait for 
event flag 2 at line 50. When one second goes by and the 
flag is set, check for one minute and update the display 
again if it hasn't yet gone by. 

Get the time and date parameters in binary. 

Use the System Library Route $DAT and $TIM to format the 
date and time for display. See Chapter 6 of the 
IAS/RSX-11 System Library Routine Reference Manual for 
documentation on these routines. 

Calculate the length of the output message by subtracting 
the starting position in the buffer from the position 
after the last character in the buffer. 

Issue the write. X*256!Y places the cursor before the 
write at line X, column Y. The TF.RCU subfunction bit 
instructs the terminal driver to save the cursor position 
before moving it, and then to restore it after writing the 
message. This allows you to continue typing in commands 
while the task runs. 

Wait for z seconds to go by. The mark time directive will 
cause event flag 2 to be set. 

Check event flag 3. If it is set, the one minute is up 
and you should exit. Use Clear Event Flag instead of Read 
All Event Flags so that the DSW will indicate whether the 
flag was clear or set before you cleared it. With Read 
All Event Flags, the settings of flags 1-16 are returned 
in a word in a buffer. You would then need to test the 
specific bit to check the flag setting, which is more 
work . 

On the Run Session - The display actually will appear at 
line X, column Y on the screen, and is updated every z 
seconds . 
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•1 

1 




2 




~z 




4 








o 




/ 




8 




7 




.1.0 




1 1 
J. X 




,L A- 




13 




1 4 
j. *t 




15 




1 A 

J. Q 




1 7 
J. / 








"19 


o 


20 




_ 21 




9 '? 

A*. Jli. 




23 




24 






0% 


o z 




T7 

/ 


w 


28 




A- 7 




ou 




" 31 


o 


32 


"7 "ST 
_ Ji3 


e 


34 


e 


35 


36 




37 




"38 




39 




40 


e 


41 




42 




43 


o 


-44 

45 


-©46 




47 




48 


o 


49 


50 




51 



♦ TITLE DATTIM 

♦ I DENT /Ol/ 

♦ ENABL LC 



y Enable lower case 



y + 

J FILE DATTIM. MAC 

9 

9 

9 
9 
9 
9 
9 
9 

i~ 



This task places the date and the time at line Xy column Y and 
then updates the display every Z seconds for .1. minute. 

Assemble and Link instructions J 

MACRO/LIST LB: CI y 1 ."JPRGGMACS/LIBRARY y dev I Cuf cHDATTIM 
LINK/MAP DATTIM y LB i I." 1 y 1 2 P R G S U B S / L I B R A R Y 



♦ MCALL QI0W*SyMRKT*yWTSE$Cy6TIM*C y External swstt 

♦ MCALL EXIT$SyCLEF*CyDIR$ y 

.MCALL DIRERRy I0ERR ? External supplied macros 



y Data 



timbuf: 

TIMMSG: 

iosb: 
mrktm: 

f Code 

start: 



X^5. 
Y=*32* 
Z==l . 

♦ BLKW 
.BLKB 

♦ BLKW 
MRKT* 



DIR* 
BCS 

y Set up for th< 
MOM 
MOM 
MOV 

again: DIR* 

BCS 

GTIM*C 

BCS 

MOM 

MOM 

CALL 

MOMB 

MOM 

CALL 
SUB 

QI0W*S 

BCS 

TSTB 

BLT 

WTSE$C 



8. 
20. 

2 

3 9 1 9 3 

♦MRKTM 
ERR! 

» other mark 
#2 9 MRKTM-f M ♦ 
#Z 9 MRKTMf M ♦ 
#2 y MRK'TM+M ♦ 
♦MRKTM 
ERR2 
TIMBUF 
ERR3 

♦TIMMSG yRO 

♦ TIMBUF y Rl 
*DAT 

♦' y<R0)+ 

♦ 3 y R2 

*TIM 

♦TIMMSG 9 RO 

♦ I'O.WLB.'TF. 
ERR4D 

IOSB 

ERR4I 

2 

ERRS 



time 
KTEF 
KTMG 
KTUN 



Line number 

Column number 

How often to update 



(in seconds) 



Buffer for return of system time 
Buffer for creating output message 
I/O status block 
DPB for mark time directive 

Set up to exit after .1. minute 
Branch on directive error 
di recti ve 
Change event flag ♦ 
C h a n g e t i in e in a g n i t u d e 
Change time units 
S c h e d u 1 e n e x t u p d a t e 
B r a n c h on d :i. r e c t i v e e r r o r 
Get system time and date 
Branch on directive error 
Set up for call to $DAT 



Convert date for display 
Insert space into output message 
Set up for call to $TIMy ask 

for HHiMMiSS format 
Convert time for display 
C o m p u t e c h a r a c t e r c o u n t 
RCU y + 5 9 ♦! y y #I0SB y y <*=TIMMSG y R0 y #X*25A . ! Y> 
y Branch on directive error 
y Check for I/O error 
y Branch on I/O error 
y Wait f o r m a r k t i m e t o e x p i r e 
ii Branch on directive error 
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© 


Ja*. 


y w 1 1 ts. i» r>. 


for 1 minute Sons by 


53 




CLEF*C 


3 


9 Clear event flag to check setting 




54 




BCS 


ERR6 


9 Branch on directive error 




55 




CMP 


$DSW?#IS*CLR r Check for flag 3 1 ready clear 




56 




BEQ 


AGAIN 


? If still clear? minute not up yet* 




57 








9 update display 3£(3in 




58 




EXIT*S 




9 Exit if 1 minute is up 




59 


f Error 


code 








60 


ERR1 : 


DIRERR 


<ERR0R 


ON MARK TIME FOR 1 MINUTE> 




61 


ERR2J 


DIRERR 


<ERRQR 


ON MARK TIME FOR 1 SECOND.'?- 




62 


ERR31 


DIRERR 


<ERR0R 


ON GET TIME> 




63 


ERR4D : 


DIRERR 


<ERR0R 


ON WRITE> 




64 


ERR4I * 


I0ERR 


#I0SB? 


< ERROR ON WRITE> 




65 


errs: 


DIRERR 


<ERR0R 


ON WAIT F0R> 




66 


ERR6 : 


DIRERR 


<ERR0R 


ON CLEAR EVENT FLAG> 




67 




♦ END 


START 






Run 


Session 








o 








12™ 


MAR-82 11 : 12 i 54 




>RUN 


DATTIM 


! DISPLAY WILL START AT LINE 5» COLUMN 32 



Example 3-7 Terminal-Independent Cursor Control (Sheet 2 of 2) 



USING THE QIO DIRECTIVE 



Formatting Output Data 

The subroutine $EDMSG in SYSLIB.OLB provides a generalized 
output formatting capability for easily creating display messages. 
It is useful if some of the data is generated at run time. This 
allows you to combine a number of functions available with 
individual conversion routines (such as $CBDMG) for converting a 
single binary word to an ASCII octal string for display. It 
includes all of the following functions. 

• Conversion of internal binary stored data to 

ASCII signed or unsigned octal 

- ASCII signed or unsigned decimal 

- ASCII alphanumeric characters 

• Conversion of time or date data into standard ASCII 
formats (hh:mm or dd-mmm-yy) 

• Formatting of converted characters for display, by 
themselves or intermixed with other text. 

For a complete discussion of the use of $EDMSG , see Chapter 5 
of the IAS/RSX-11 System Library Routine Reference Manual . 

To invoke $EDMSG, use the following procedure. 

1. Set up the output buffer, the format string, and the 
argument block. 

2. Set up the input parameters. 



R0 



starting address of output buffer 



Rl 



starting address of format string 



R2 



starting address of argument block, containing 
the data to be converted 



3. 



Call $EDMSG. 
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On return, the converted/formatted string is in the output 
buffer. The output parameters are: 

R0 - Address of next available byte in the output buffer 

Rl - Length (in bytes) of the output string 

R2 - Address of the next argument in the argument 
block. 

NOTE 

The output parameters make it possible to 
concatenate messages using multiple calls to 
$EDMSG. 

The output buffer is a buffer in which $EDMSG generates the 
output message. It is typically set up using the .BLKB or .BLKW 
assembler directive. The format string is set up using a 
combination of ASCII text and editing "directives." It must be in 
ASCIZ format, meaning that it is terminated by a 0(8). The 
editing "directives" are in one of three formats, as follows. 

%d - Means perform directive d once 

%nd - Means perform directive d n-times 

%Vd - Means perform directive d V-times, where V is an 
argument in the argument block. 

For example, if %0 means convert binary word to ASCII signed 
octal, %0 means convert the next word in the argument block to 
ASCII signed octal in the output buffer. %30 means convert the 
next three words to ASCII signed octal in the output buffer, 
separated by tabs. %V0 means get the binary word in the argument 
block and convert that many words in the argument block to signed 
octal in the output buffer. 

Table 3-4 shows many of the editing directives available with 
$EDMSG. An example follows the table. 
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T3ble 3 " 4 Sa ">Ple Editing Directive , * 

tlves for $EDMqr 
ion Di recti voo »*DMSG 



Conversion Directives 
Directive Meaning 



D 



U 







Convert binary word in 
binary block to ASCrr 
signed decimal 11 

Convert binary word i n 
argument block to asctt 
^signed decimal? 11 

Convert binary word in 
argument block to ASC?r 
signed octal. 11 

Convert binary word in 
argument block to asc?t 
unsigned octal. 1 

Convert RAD 50 word i n 
argument block to ASCII . 

Convert three words to 
dd-mmm~yy format. 

Convert time parameter (s) 
to hh:mm: SS ,s format J 

i?c r .r Part - hh only, 

at V th' he „ ASCl1 ^aracter 
to fn %K ddreSS Panted 
t0 ln the argument block. 



Fo rmatting 
Di rective 



N 



Directives 
Meaning 

Form feed 



Line feed 



Space 
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Example : 

FORMAT : 

OUTBUF: 
DATA: 

ADRNAM : 



.ASCIZ 

.EVEN 

. BLKW 

.WORD 

.WORD 

.ASCII 

.EVEN 



/%10$NAME IS %5A AND # IS %D/ 
80. 

ADRNAM 
234 

/BILLY/ 



MOV #OUTBUF, R0 

MOV # FORMAT, Rl 

MOV # DATA , R2 

CALL $EDMSG 

The resulting string in OUTBUF would display as 

NAME IS BILLY AND # IS 156 



Explanation : 

%10S in the format string - Produces 10 spaces in the output 
buffer . 

NAME IS - Placed in the buffer as is. 

%5A - Get five bytes and convert to ASCI 
argument block is set up on a word-by-word 
address of the ASCII characters (ADRNAM) , 
ASCII characters themselves, in the argument 

AND # IS - Moved to the output buffer as is. 

%D - Get the next binary word in the argument block and 
convert it to signed decimal in the output block. 234(8) is 
converted to +156(10). 

No decimal point is appended to decimal numbers unless you 
specify %D. (including the ".") in the format string. 



I. Because the 
basis, place the 
instead of the 
block . 
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Three examples follow which demonstrate the use of the $EDMSG 
routine . 



Examples of Formatting Numeric Data 

Example 3-8 shows the use of $EDMSG for formatting numeric 
data. The following notes are keyed to the example. 

O This is the argument block, which must be a set of 
contiguous words. 

Q This example uses the $ form of the QIO directive. The 
length of the buffer to be written out will be filled in 
at run time. 

Q The output buffer starts at BUF and is 80. bytes long. 
This buffer should be long enough for at least the longest 
message that you might generate. 

Q The format string. Note that three words will be 
converted to signed decimal ASCII using $EDMSG. The 
.ASCIZ assembler directive assures that the format string 
ends with an octal 0. 

O Set up input parameters for call to $EDMSG. The addends 
and the sum are already in the argument block. 

O Invoke $EDMSG. The output string is returned at BUF. Rl 
contains the count of characters in the output string. 

O Move the count of characters to be written into the DPB of 
the QIO$ directive. 

O Write the results out at the terminal. 

Normally, the addends might be placed in the format string if 
they are known at assembly time. Only data generated at run time 
would be converted using $EDMSG. 



139 



USING THE QIO DIRECTIVE 



O 

e 



i 

3 
4 
5 
6 
7 
8 
9 
1.0 
.1.1 
12 
13 
14 
1.5 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
) 26 
027 
28 
29 
30 
31 
32 
33 
34 
35 
36 



♦ TITLE 

♦ I DENT 
♦ ENABL 



NUMER 

/01/ 

LC 



5 Enable lower esse 



9 + 

9 



FILE NUMER* MAC 

This task does a simple addition 



results* It demonstrates the use 
formatting messages with numeric 



9 Data 
AJ 

c: 



♦ MCALL. 
♦ NLIST 



♦ WORD 

♦ WORD 

♦ BLKW 



QIOW*>EXIT*S>DIR* 

BEX 9 



10 

22 
1 



OUTi QIOW* I0*WVBy5?l» ylOSBv 9 

9 

* BLKW 2 9 
up for $EDMSG 



iosb: 

9 

9 Set 

9 

buf: 

FMES* 



START J 



and outputs the 
of *EDMSG for 

data 

9 System macros 
Do not list binary 
extensions 

1st addend and start 

of argument block 
2nd addend 
Location for sum 

<BUF? ?40> 9 QIO for 

output message 
I / status bio c k 



* BLK'B 
*ASCIZ 



♦ LIST 

♦ EVEN 
MOV 



ADD 



80* 
/ZD* 



BEX 
AyC 
B*C 



WAS ADDED TO 



Output buffer 
%D* 9 GIVING %D*/ 
Format string 

List binary extensions 
Move to word boundary 
Move 1st addend to sum 
word 

Add 2nd addend to form 
sum 



9 Set up for call to $EDMSG 



"37 


MOV 


#BUFs-R0 


9 


Addr of output buffer 


38 


MOV 


♦FMESyRl 


9 


Addr of format string 


_39 


MOV 


#A 9 R2 


9 


Addr of argument block 


40 


CALL 


*EDMSG 


9 


Make call* character 


41 






9 


count returned in Rl 


42 


MOV 


Rl>0UT+Q*I0PL+2 


9 


Place # of characters 


43 






9 


to write into I0PL 


44 






9 


in QIO DPB 


45 


DIR* 


#0UT 


9 


Write output message 


46 


BCS 


ERR ID 


9 


Branch on dir error 


47 


TSTB 


IOSB 


9 


Check for 1/0 error 


48 


BLT 


ERR 11 


9 


Branch on 1/0 error 


49 


EXIT$S 
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50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 



y Error handling 
ERR ID: MOV *BSWrRO 
CLR Rl 

IOSBrRO 
#-lyRl 

START 



IOT 

ERRli: MGVB 
MOv" 

IOT 
♦ END 



9 Move DSW for display 
5 Indicate dir error? by 
y in Rl 

y Move I/O status for 
y display 

y Indicate I/O error by 
y -1 in RO 



Run Session 
>RUN NUMER 

8* WAS ADDED TO 18* y GIVING 26* 
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Example 3-9 shows how to use $EDMSG to generate error 
messages for display. This is a modification of Example 3-1 
(SYNCHQ . MAC) . These error routines will typically replace trap 
routines which might be used early in the debugging stage of an 
application. The supplied macros DIRERR and IOERR have performed 
similar functions for you. The following notes are keyed to the 
example . 

O This is the assembly time setup for $EDMSG. ARG is the 
start of the one word argument block. EBUFF is the start 
of the buffer in which error messages are to be built. 
FMT1, FMT1A, FMT2 , FMT2A are the format strings for the 
various error messages. FMT1 and FMT2 are for directive 
errors; FMT1A and FMT2A are for I/O errors. The 
quotation marks are used as delimiters in two of the 
format strings because the strings contain slashes (/) . 



Q The main code is the same as before, 
handling is different. 



Only the error 



For each error, move the address of the appropriate format 
string into Rl (for the call to $EDMSG) . Then move the 
DSW into the argument block for directive errors, and the 
I/O status into the argument block for I/O errors. 
Because the I/O status is a byte, move it to Rl first and 
then to the argument block, in order to extend the sign 
bit to the high order byte (see lines 0064 and 0065). 
Then branch to the final setup for $EDMSG at EDAWT. 
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Move the address of the output buffer to R0 and of the 
argument block to R2. Then call $EDMSG . 

Finally, write the formatted message out at the terminal 
and exit. 

On the Run Session - The first run shows a successful 
read. The second run shows an error caused by a ~Z. 



USING THE QIO DIRECTIVE 



♦TITLE SYNQER 
♦IDENT /Ol/ 
♦ENABL LC 



r Enable lower case 



J FILE SYNQER* MAC 



6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
.25 
26 
27 
'28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 



This task reads 3 line of text from the terminal y 
converts all upper case characters to lower case? and 
prints the converted message b3ck at the terminal* It 
uses synchronous QI0» It 3lso uses $EDMSG to generate 
error messages 



♦MCALL QIQW*C>QI0W*S>EXIT*S f System macros 



iosb: 
buff: 



♦ BLKW 

♦ BLK'B 



80* 



9 1/0 Status Block 
t Text buffer 



i Set up for error messages using $EDMSG 



arg: 
ebuff: 

FMT1 * 
FMT1AJ 
FMT2 i 
FMT2A* 



♦ BLKW 

♦ BLK'B 
♦ASCIZ 
♦ASCIZ 
♦ ASCIZ 
♦ ASCIZ 

♦ EVEN 



1 9 Argument block 

SO* 9 Output buffer 

/DIRECTIVE ERROR ON READ* DSW = ZD/ 
' I/O ERROR ON READ? I/O STATUS = ZD' 
/DIRECTIVE ERROR ON WRITE? DSW ~ ZD/ 
'I/O ERROR ON WRITE? I/O STATUS = ZD' 



Issue 



START: QI0W*C I0»RVBy5>l» >I0SB* ?<BUFFp80* 9 40> 

9 read 

Branch on dir error 
Check for I/O error 
Branch on I/O error 
Get charscter count 
Offset into buffer to 

character 
Check for upper case 

ASCII char3cter 
Brsnch if below rsnge 



loop: 



BCS 

TSTB 

BLT 

MOV 

CLR 

CMPB 



ERR 1 

IOSB 

ERR1A 

I0SB+2?R0 

Rl 

BUFF(Rl) >#'A 



BLT 
CMPB 
BGT 

9 Here if upper 
MOVB 
ADD 
MOVB 

next: INC 

SOB 

QI0W*S 

BCS 

TSTB 

BLT 

EXIT$S 



NEXT 
BUFF(Rl) r*'Z 
NEXT 

case? move to 
BUFF(Rl) ?R2 
#32* 9 R2 
R2?BUFF(R1) 
Rl 

R0?L00P 

#I0*WVB?#5?*1 

ERR2 
IOSB 
ERR2A 



i Branch if above range 
register R2 and convert 
9 Move to register 
9 Convert to lower case 
9 Replace in mess3ge 
9 Increment offset into 
9 buffer to next char 
9 Decrement count of 
9 chars left to check 
9 ?#I0SB? ? <#BUFF?I0SB+2?#40:: 
f Write text 
i Branch on dir error 
9 Check for I/O error 
9 Branch on I/O error 
9 Exit 



ample 3-9 Formatting Directive and I/O Error Messages 
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O 

e 



56 
57 

'58 
59 
60 
63. 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 

'78 
79 

.80 
8.1. 
82 
83 
84 



? Error code 
ERR1 A * MOV 
BR 

ERR2A* MOV 

errgoa: movb 

MOV 



ERR1 : 



ERR2 ♦ 



BR 
MOV 
BR 
MOV 



♦FMTlAyRl 

ERRGOA 

#FMT2A*R1 

lOSByRO 
RO y ARG 

EDAWT 
#FMT1 fRi 
ERRGO 
#FMT2yRl 
#$DSWy ARG 



ERRGO * MOV 
i Finish setting up for $EDMSG 
EDAWT * MOV #EBUFF»RO 

MOV #ARG>R2 

CALL $EDMSG 

OIOW*S #I0*WVBy#5y*l> * y 

EXIT*S 
♦END START 



Format string for 

1st I/O error message 
Branch to common I/O 

error code 
Format string for 2nd 

I/O error message 
Extend sign on I/O 

status byte by moving 

it through RO to the 

argument block 
Branch to common edit 

and write code 
Format string for 1st 

directive error 
Branch to common 

directive error code 
Format string for 2nd 

directive error 
Move DSW to arg block 

Output buffer address 
Argument block address 
Edit output string 
:#EBUFF>R1>#40> ? Write 

out message 
Exit 



Run Session 
>RUN SYNGER 

SKJDSHKJKHkJhkJhkJhkyutduyeJherwer Jwll2 

skJdshk JkhkJhkJhkJhkyutduyeJherwer Jwl 12 

>RUN SYNQER 

d h f i o o i J K L H J G H J G J H G ~ Z 

I/O ERROR ON READ* I/O STATUS = -10 



Example 3-9 Formatting Directive and I/O Error Messages 
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Formatting ASCII Data 

Example 3-9 demonstrates the use of $EDMSG for formatting 
ASCII data. The only real difference between formatting ASCII 
data as compared to numeric data is that the argument block 
contains a pointer to the ASCII characters, rather than to the 
ASCII data itself. The following notes are keyed to the example. 

O The argument block contains four words. Only the address 
of the number to be typed is known at assembly time. The 
other values will be filled in at run time. In the format 
string, we are using %VA twice. The V tells $EDMSG to use 
the next word in the argument block as the number of times 
to perform the directive A. The directive A means move an 
ASCII character to the output buffer. This allows you to 
generate messages of different lengths at run time using 
the same format string. 

O An alternative to using TSTB is to use a CMPB instruction. 
IS. SUC is a global symbol equal to +1. 

Q The number typed is in ASCII. We need to convert to 
binary before dividing by two. 

Q Come here if the number is even. Place the address of the 
message and its length into the argument block. Then 
branch to the common code to generate the message. 

Q This is the same as in note 4, but for an odd number. 

O Move the number of digits in the number entered by the 
operator to the argument block; so you display that many 
digits . 

Q Now set up for $EDMSG, format the output message, write 
it, and exit. 

Now do the tests/exercises for this module in the 
Tests/Exercises book. They are all lab problems. Check your 
answers against the solutions provided, either in that book or 
on-line files. 

If you think that you have mastered the material, ask your 
course administrator to record your progress in your Personal 
Progress Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, 
return to this module for further study. 
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1 




♦ TITLE 


FORMAT 




'? 




♦ I DENT 


701/ 




3 




♦ ENABL 


LC y 


Enable lower case 


4 
5 


9 + 

y FILE 


FORMAT ♦ MAC 




6 
7 


$ 

y This 


task ask 


s the user for an 


integer* It then 


8 


r decides whether the value is even or odd* and prints 


Q 

7 


y so appropriate message* It demonstrates the use of 


10 


•5 *EDMSG for ASCII data 




11 


y 








12 


i Assemble and 


task-build instructions J 


13 


y 








:L4 


9 


MACRO/LIST LB * CI y 1 3PR0GMACS/LIBRARY y dev ♦ L'uf dTJFGRMAT 


15 


y 


LINK/MAP FORMAT y LB* III y 1 3PRQGSUBS/LIBRARY 


16 


r — 








17 




♦ MCALL 


EXIT$SyQIOW*CyQIOW$S y System macros 


18 

19 




♦ MCALL 


DIRERRy I0ERR y 


Supplied macros 


20 


MES ♦ 


♦ASCII 


/INPUT A DECIMAL 


INTEGER BETWEEN 1 AND 9999/ 


21 






y 


Prompt text 




LEN 




♦ ~MES f 


Length of prompt text 


23 




."EVEN 






24 


NUMJ 


♦ BLKB 


4 y 


Buffer for ASCII # input 


25 




♦ EVEN 






26 


iosb: 


♦ WORD 


y 


I/O Status Block 


27 


NUMB t 


♦ WORD 


y 


2nd word of I/O Status 


28 






y 


Block ~ for return of 


09 






y 


# of characters read 


30 


r Setup 


for *EDMS6 




31 


ARGBLK * 








32 


LNUMi 


♦ WORD 


y 


Count of characters 


33 






.V 


in number 


34 


ANUM ♦ 


♦ WORD 


NUM y 


Pointer to number in ASCII 


35 


lword: 


♦ WORD 


y 


Count of characters 


36 






!> 


in ODD or EVEN 


37 


a word: 


♦ WORD 


y 


Pointer to ODD or EVEN 


38 






y 


in ASCII 


39 


BUF i 


♦ BLKB 


80 ♦ y 


u t p u t b u f f e r 


40 


out: 


♦ASCIZ 


/%NTHE NUMBER %VA 


is %VA*/ y Format string 


4.1. 


mese: 


♦ASCII 


/EVEN/ y 


ASCII text for EVEN 


42 


LMESE 


-♦-MESE 


y 


Length of message 


43 


meso: 


♦ASCII 


/ODD/ y 


ASCII text for ODD 


44 


LMESO 


= ♦ -MESO 


y 


Length of message 


45 




♦ EVEN 






46 


r 








47 


start: 


QI0W*C 


I0*WVBy5yl.y ylOSBy 


y<MESy|_ENy40> * Write 


48 






y 


prompt text 


49 




BCS 


ERR ID y 


Branch on dir error 


50 




CMPB 


#IS ♦ SUC y IOSB y* 


Check I/O Status 


51 




BNE 


ERR 11 y 


Branch on I/O error 


52 




QI0W*C 


I0*RVBy5yly ylOSBy 


y<NUMy4> y Read input 


53 




BCS 


ERR2D } 


Branch on dir error 


54 




TSTB 


IOSB 5 


Check on I/O error 


55 




BLT 


ERR2I y 


Branch on I/O error 



Example 3-10 Formatting ASCII Data (Sheet 1 of 2) 
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56 
57 
58 
5? 
60 
6.1. 
62 
63 
64 
65 
66 
67 
68 
69 
70 
7.1. 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 



Set 



ODD I 



CO NT * 



MOV 

CALL 
up for 
CLR 
DIV 

CMP 
BNE 

MOM 

MOV 

BR 
MOV 

MOV 

MOV 



i Error 
ERR ID * 

errii: 

ERR2D t 
ERR2I ♦ 
ERR3D i 
ERR3I: 



tNUMyRO 

*CDTB 

d i v :i. die * D i v i d e n d 
RO 

#2yR0 



MOV 
MOV 
MOV 
CALL 
QIQW*S 

BCS 
CMPB 

BNE 

EXIT*S 
handl ins* 
DIRERR 
IOERR 
DIRERR 
IOERR 
DIRERR 
IOERR 
. END 



y Set up to convert 
y dec ASCII to binary 

y Convert r result in R:L 

R y R 1 c o in b i n e d 

? Clear high order 16 bits 

y Divide y Quotient, in ROy 
? remainder in Rl 

Rly#0 y Check remainder 

ODD ? Branch if not 

#LMESE y LWORD y Move length of EVEN 
y into argument block 

y Move pointer to EVEN 
y into argument block 

y Branch to common code 

y Move length of ODD 
y into argument block 

y Move pointer to ODD 
y into argument block 

y Move # of characters 
y in number to arg block 

y Set up for call to *EDMSG 



#MESE y A WORD 
CONT 

tLMESG y LWORD 

#MES0vAW0RD 

NUMBpLNUM 

tBUFyRO 
#0UTyR:l. 
#ARGBL.KyR2 
*EDMSG 



y Edit output message 
# 1 * W VB .» #5 y # 1. y y # I OSB y y <#BUF y R .1. t #40> 

y Write output message 

y Branch on dir error 

y Check for I/O error 

y Branch on I/O error 

$ Exit 



ERR3D 

#IS*SUC»IOSB 

ERR 3 1 



OF PROMPT TEXT> 
WRITE OF PROMPT 



<ERR0R ON WRITE 
# I OSB TERROR ON 
< ERR OR ON READ> 
#1 OSB TERROR ON READ> 
<ERR0R OUTPUTTING ANSWER> 
#I0SB»<ERR0R OUTPUTTING ANSWER 
START 



TEXT> 



Run Session 
>RUN FORMAT 

INPUT A DECIMAL INTEGER BETWEEN 1 AND 9999 
600 

THE NUMBER 600 IS EVEN* 
>RUN FORMAT 

INPUT A DECIMAL INTEGER BETWEEN 1 AND 9999 
2349 

THE NUMBER 2349 IS ODD ♦ 



Example 3-10 Formatting ASCII Data (Sheet 2 of 2) 
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USING DIRECTIVES FOR INTERTASK COMMUNICATION 



INTRODUCTION 

The RSX-11M program development features allow modular 
development of programs; the multitasking feature allows a 
modular approach to applications. 

A system of multiple tasks may require one or more of the 
following services provided by executive directives under RSX-11M. 

• First task requests that the second task be run. 

• First task is notified of completion of the second task 
operation . 

• Tasks pass data to each other. 

This module explains how to use system directives for this 
type of coordination between tasks. 



OBJECTIVES 

1. To use directives which control task execution to 
synchronize cooperating tasks 

2. To use the send/receive directives to pass data between 
tasks . 

3. To write tasks which spawn subtasks using parent/offspring 
d i rectives . 



RESOURCE 

• RSX-11M/M-PLUS Executive Reference Manual , Chapters 2 and 
4, plus specific directives in Chapter 5 
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USING TASK CONTROL DIRECTIVES AND EVENT FLAGS 

It is generally good programming practice to divide a single 
complex task into a number of separate tasks, with each task 
performing a distinct logical function. Using a group of tasks to 
perform a complex function frequently makes good sense, especially 
where different parts of the process may run at widely differing 
speeds, each more or less independent of the others. 

Suppose, for example, that you need to simulate customer 
transactions at a bank. There are five windows, up to 15 
customers can physically stand in each line at a time, given the 
size of the waiting area. You might design a group of tasks, one 
task per line, to simulate this complex system. This approach has 
the advantage of simulating the related, but essentially parallel, 
processes in a more realistic manner than would a single, serial, 
simulation. A further advantage of a multitasking approach to 
such a job is that changes in the behavior of the system that are 
caused by changes in a single line (e.g., by assigning different 
types of transactions to different lines) can easily be simulated 
by simply modifying the task that simulates that line. 

An RSX-11M programmer typically uses a mix of the following 
four multitasking methods. 

1. Common or Group Global event flags, together with 
synchronization and task scheduling directives, are used 
to synchronize tasks. 

2. Resident commons are used to share data in memory. 

3. Memory management directives are used to create and/or 
share data areas dynamically at run time. 

4. File handling routines are used to open disk files for 
shared access. 

The use of shared regions, memory management directives and 
files are discussed in later modules. 
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Directives 

Table 4-1 lists the various task control directives which are 
available for task synchronization. (Most of these were discussed 
in earlier modules.) All of the directives are documented 
individually in Chapter 5 of the RSX-11M/M-PLUS Executive 
Reference Manual . 

Table 4-2 shows the differences between suspending and 
stopping a task. The major difference is that stopping puts the 
task in a stopped state which effectively lowers the task priority 
to zero, allowing any active task to checkpoint it if it is 
checkpointable. Suspending or waiting, on the other hand, keeps 
the task competing for memory space on the basis of its running 
priority. This means that if the task is checkpointable, only 
tasks of higher priority checkpoint it. Waiting for an event flag 
affects checkpointabili ty the same way as suspending. 

Table 4-3 lists the various event flag directives which are 
available for synchronization. As discussed in Module 2, the 
Clear Event Flag directive (CLEF$) can be used instead of the Read 
All Event Flags (RDAF$) or the Read Extended Event Flags (RDXF$) 
directives, to check whether a single event flag is set (since the 
DSW indicates whether the flag was initially clear or set) . This 
saves having to check the specific bits in the event flag mask 
word. Checking specific bits is necessary with RDAF$ and RDXF$ 
because they return several event flag mask words, each containing 
the settings of 16 flags, one flag per bit. 
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Di rective 

MACRO 

RQST$ 
RUN$ 



ABRT$ 

SPND$ 
STOP$ 



RSUM$ 
USTP$ 



Table 4-1 Task Control Directives 
and Their Use for Synchronizing Tasks 

Example of Use for Synchronization 



Issuing task activates target task. 
Target task then performs some operation 
for issuing task. 

Issuing task aborts target task. 

A task suspends or stops itself to 
wait for completion of another 
task operation. 

A task suspends or stops itself 
until it is needed by another task. 

A task resumes or unstops another 
task which has suspended or stopped 
itself while waiting for that task 
to complete some operation. 

A task resumes or unstops another 
task when it needs the other task's 

A task can also be resumed by: 

- Its own AST routine 

- Operator use of a DCL CONTINUE command 
(RESUME in MCR) . 

A task can be unstopped by: 

- Its own AST routine 

- Operator use of a DCL START command 
(UNS in MCR) . 
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Table 4-2 Stopping Compared to Suspending or Waiting 



Stopping 

Priority is effectively 
dropped to zero. 

Task can be checkpointed 
by any other task (if 
checkpointable) . 

Chance of being 
checkpointed increases. 

Frees memory for other 
tasks . 



Task response time 
increases dramatically 
if task is checkpointed. 



Suspending or Waiting 
Priority remains unchanged. 



Task can be checkpointed 
only by tasks of higher 
prior i ty. 

Chance of being check- 
pointed remains normal. 

Continued allocation of 
memory can block out lower 
priority tasks. 

No change in task response 
time, because no change 
in likelihood of being 
checkpointed . 



Di rective 

MACRO 

CLEF$ 

SETF$ 



WTSE$ 
STSE$ 



STLO$ 
WTLO$ 

RDAF$ 
RDXF$ 



Table 4-3 Event Flag Directives and 
Their Use for Synchronizing Tasks 

Example of Use for Synchronization 



A task clears the event flag, then waits 
for it to be set by another task. 

A task performing an operation for 
another task sets an event flag to 
signify completion of the operation. 

A task waits for completion of an 
operation by another task by waiting 
or stopping for that task to set an 
event flag . 

A task waits or stops for the completion 
of the first of some set of operations. 

A task tests for completion of an 
operation by another task, without 
waiting or stopping for it. 
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Example 4-1 shows the use of the Request Task (RQST$) , 
Suspend (SPND$) , and Resume (RSUM$) directives for 
synchronization. Notes 1, 2, 3 and 6 refer to TASKA. Notes 4 and 
5 refer to TASKB. 

O Tne supplied macros are used to allow you to concentrate 
on the synchronization techniques. If you want, these 
macros can be replaced with QIO's and other code. 

Q TASKA requests TASKB. This means that TASKB must be 
installed under the name TASKB. After this, both tasks 
are active and compete for memory and CPU time. 

O TASKA suspends itself. After this it still competes for 
memory at its regular priority, but not for CPU time. 

Q TASKB types out a message and then resumes TASKB. More 
typically, TASKB would perform some service for TASKA 
rather than just typing a message. After TASKB resumes 
TASKA, they both compete for CPU time again. 

Q TASKB displays another message and then exits. 

Q TASKA, now resumed, displays a message and exits. 

Depending on the relative priorities of TASKA and TASKB and 
on the particular task scheduling options on your system (e.g., 
round robin scheduling) , steps 5 and 6 may be reversed on the run 
session . 
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♦TITLE TASKA 
* I DENT /Ol/ 
♦ENABL LC 



r En3ble lower case 



4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
2^ 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 



S> FILE TASKA ♦ MAC 



r This task requests TASKB to run* and then suspends 

9 itself* TASKB resumes this task and exits* 

i 

r Assemble and t3sk~build instructions* 
? 

? MACRO/LIST LB * C 1 » 1 3PR0GM ACS/LIBRARY r dev * Cuf d3TASKA 

r LINK/MAP LB* CI » 13TASKA*PR0GSUBS/LIBRARY 

r 

5 Install and run instructions* Both tasks must be 

$ installed* Just run TASKA* 

i 

♦ MCALL RQST$Ci>SPND$SyEXIT*S i System macros 
♦MCALL TYPE* DIRERR r Supplied macros 

r 

start: type <taska begins and REQUESTS taskb> 

y Display message 
RQST*C TASKB ? Reauest TASKB 

BCC OKI ? Branch on directive ok 

DIRERR <TASKA UNABLE TO REQUEST TASKB> $ Display 

9 error message and exit 
OKU TYPE < TASK A IS SUSPENDING ITSELF> 5 Display 

9 message 
SPND$S i Suspend self 

BCC 0K2 9 Branch on directive ok 

DIRERR <TASKA UNABLE TO SUSPEND> ? Display 

i error message and exit 
0K2J TYPE <TASKA HAS BEEN RESUMED> 5 Display 

9 message 

EXIT$S J Exit 

* END START 



Example 4-1 Synchronizing Tasks Using Suspend and Resume 

(Sheet 1 of 2) 
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3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
02 
23 
24 
05 

26 
27 

"28 
29 

.30 
31 
32 
33 

"34 
35 

.36 
37 



♦TITLE TASKS 
♦ I DENT /Ol/ 
♦ ENABL LC 



? Enable lowercase 



i FILE TASKB ♦ MAC 



9 This task is activated by TASKA* It performs its 

5 operation and resumes TASKA? which has suspended 

? itself* 
9 

9 Assemble and link instructions* 
9 

9 MACRO/LIST LB J CI r 1 3PR0GMACS/LIBRARY t dev : Cuf d!] TASKB 

9 LINK/MAP TASKB 9 LB : C 1 1 1 .JPROGSUBS/LIBRARY 

V 

9 Install and run instructions J Both tasks must be 

9 installed* Just run TASKA* 

9 

♦ MCALL RSUM$C?EXIT$S 5 System macros 
♦MCALL TYPE? DIRERR 9 Supplied macros 

9 Must enable local symbol blocks because we use local 
9 symbols and DIRERR has *PSECT statements 

♦ENABL LSB 9 Enable local symbol 

9 block* 

9 

9 Any operation could be performed here? but in this 
9 case it's only a typeout* 

START i TYPE <TASKB IS ALIVE AND RUNNINGS- ? Display 

9 message 
RSUM*C TASKA 9 Resume TASKA 

BCC 1$ 9 Branch on directive ok 

DIRERR <TASKB UNABLE TO RESUME TASKA> r Display 

9 error message and exit 
1*: TYPE <TASKB HAS RESUMED TASKA AND IS EXITING!:- 

5 Display message 
EXIT*S i Exit 

♦ END START 



Run Session 

>INS TASKA 
>INS TASKB 
>RUN TASKA 

TASKA BEGINS AND REQUESTS TASKB 
TASKA IS SUSPENDING ITSELF 
TASKB IS ALIVE AND RUNNING 
TASKA HAS BEEN RESUMED 

TASKB HAS RESUMED TASKA AND IS EXITING 



Example 4-1 Synchronizing Tasks Using Suspend and Resume 

(Sheet 2 of 2) 
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Example 4-2 shows the use of event flags for synchronization. 
In module 2, there is a similar example. Here, TASKC requests 
TASKD, rather than requiring an operator to start both tasks. 
Also, the Stop For Single Event Flag is used rather than the Wait 
For Single Event Flag. The difference between them is that the 
first causes the task to enter a stopped state and the other 
causes the task to enter a wait for (like a suspended) state. 
Notes 1, 2, 3 and 6 refer to TASKC. Notes 4 and 5 refer to TASKD. 



o 


Clear the event flag to initialize it. It's initial state 
is unpredictable, since other tasks may have set or 
cleared it. 


e 


Request TASKD. 




e 


Stop until the 


event flag is set by TASKD. 


o 


TASKD displays 


a message and sets the event flag. 


e 


TASKD displays 


a message and exits. 


e 


TASKC displays 


a message and exits. 


Depending on the 


relative priorities of the two tasks, 



significant events in the system, and other scheduling 
considerations, the order of the steps may vary. Specifically, 
steps 3 and 4 above may be reversed, as well as 5 and 6 . 

The event flag must be common or group global, not local. In 
either case, the users on the system must coordinate to avoid 
several users using the same event flag for different purposes. 
If a group global event flag is used, the flags for that group may 
have to be created using either the Create Group Global Event 
Flags directive (CRGF$) or the DCL SET GROUPFLAGS/CREATE (FLA /CRE 
in MCR) command. 

The Executive scans the Active Task List and schedules tasks 
for CPU time only after a significant event. Setting an event 
flag does not cause a significant event. This means that TASKC 
normally won't compete for CPU time until at least the next 
significant event in the system. If it is important that TASKC 
begin executing sooner than that, TASKD should issue the Declare 
Significant Event directive (DECL$), which causes the Executive to 
reschedule tasks. For a discussion of significant events, see 
Chapter 2 of the RSX-11M/M-PLUS Executive Reference Manual. 
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1 

X 




♦ TITLE 


TASKC 




2 




♦ I DENT 


/Ol/ 




3 




* ENABL 


LC 


9 Enable lower case 


4 

5 


? + 

9 FILE 


TASKC ♦ MAC 




6 
7 


r 

y This 


task clears an 


event flag* requests TASKD to run? 


8 


9 and 


then stop 


s until 


the flag is set by TASKD* 


9 


9 

i Assemble and 


t ask -bu i 1 d i ns t ruct i oris : 


11 


9 








12 


9 


MACRO/LIST LB: 


CI 9 1 3 P R G M A C S / L I B R A R Y y d e v : L' u f d .1 TASKC 


13 


9 


LINK/MAP TASKC 


9 LB : C 1 9 1 DPROGSUBS/LIBRARY 


14 


9 








IS 


9 Install and run instructions* TASKD must be installed* 


16 


9 Just 


run TASKC ♦ 




17 


9 — 








18 




♦MCALL 


CLEF*C 


*RQST*C»STSE*C>EXIT*S ? System macros 


19 




♦MCALL 


TYPE 9 DIRERR 5 Supplied macros 


20 

21 
/•)/•} 


9 

FLAG=33* 




9 Event flag to be used 


23 


9 

start: 


TYPE 


•CTASKC 


BEGINS AND REQUESTS TASKD> 


24 








? Display message 


25 




CLEF*C 


FLAG 


9 Clear event flag 


26 








9 before stopping 


27 




BCC 


OKI 


9 Branch on directive ok 


28 




DIRERR 


<TASKC 


UNABLE TO INITIALIZE EVENT FLAG> 


29 








9 Display error message 


30 








9 and exit 


31 


OKI i 


RQST*C 


TASKD 


9 Reouest TASKD 


32 




BCC 


0K2 


9 Branch on directive ok 


33 




DIRERR 


<TASKC 


UNABLE TO REQUEST TASKD> ? Display 


34 








i error message and exit 


35 


0K2J 


TYPE 


<TASKC 


IS STOPPING FOR EVENT FLAG> 


36 








9 Display message 


37 




STSE*C 


FLAG 


9 Stop for event flag 


38 








9 to be set 


39 




BCC 


OK 3 


9 Branch on directive ok 


40 




DIRERR 


<TASKC'S STOP REQUEST REJECTED::- 5 Display 


41 








9 error message and exit 


42 


0K3: 


TYPE 


<TASKC 


HAS BEEN UNSTOPPED AND WILL NOW EXIT.'. 


43 








9 Display message 


44 




EXIT*S 




y Exit 


45 




♦ END 


START 





Example 4-2 Synchronizing Tasks Using Event Flags 

(Sheet 1 of 2) 
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♦TITLE TASKD 
♦ I DENT /0:l./ 
♦ENABL LC 



? Enable lower case 



6 
7 
8 
9 
10 
11 

13 
14 
15 
16 
17 
18 
19 
20 
21 
22 

'23 
24 

.25 
26 
27 
28 
29 
30 

"31 
32 

.33 
34 



$ FILE TASKD ♦ MAC 



f This task is activated by TASKC ♦ It sets the flag for 

y which TASKC is stopped* 

5 

? Assemble and task-build instructions* 

9 

* MACRO/LIST LBJClyl-IPROGMACS/LIBRARYycJevJ ? Cuf diJTASKD 

? LINK/MAP TASKD * LB ill 9 1 3PR0GSUBS/LIBRARY 

i — 

♦ MCALL SETF$C*EXIT*S r System macros 
♦ MCALL TYPE * DIRERR ? Supplied macros 

9 

FLAG-33* f Event flag 



9 Any operation could be performed here? but in this 
9 case it's only a typeout* 

START: TYPE <TASKD IS ALIVE AND RUNNING::- 5 Display 

9 message 

SETF$C FLAG ? Set the flag to allow 

9 TASKC to be unblocked 
BCC OK 9 Branch on directive ok 

DIRERR <TASKD UNABLE TO SET EVENT FLAG> 

9 Display error message 
9 3nd exit 

OK: TYPE <TASKD HAS SET THE EVENT FLAG AND IS EXITING 

9 Display message 
EXITSS 9 Exit 

♦END START 



Run Session 

>INS TASKC 
>RUN TASKC 

TASKC BEGINS AND REQUESTS TASKD 
TASKC IS STOPPING FOR EVENT FLAG 
TASKD IS ALIVE AND RUNNING 

TASKD HAS SET THE EVENT FLAG AND IS EXITING 
TASKC HAS BEEN UNSTOPPED AND WILL NOW EXIT 



Example 4-2 



Synchronizing Tasks 
(Sheet 2 of 2) 



Using Event Flags 
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SEND/RECEIVE DIRECTIVES 
General Concepts 

The Send and Receive directives are used to transmit a 13. 
word block of data between tasks. The sequence of events is as 
follows . 

1. A task issues a Send Data request, specifying a receiver 
task and a data buffer. 

2. The Executive copies the data buffer into a data packet in 
the dynamic storage region (DSR or pool) . 

3. The Executive places the data packet FIFO 
(first-in-first-out) into the receive queue of the 
specified receiving task. 

4. Later, the receiving task issues a Receive Data request, 
specifying a data buffer. 

5. The Executive copies the data packet into the buffer 
specified by the receiving task. 

Directives 

Table 4-4 lists the Send Data directive and the various 
Receive Data directives. The differences among the Receive Data 
directives concern what happens if there are no data packets in 
the receiver's receive queue. 

All receive directives receive 15(10) words, including the 
sender task name (in Radix-50 format) plus the data. If no sender 
task is specified in a Receive Data directive, the first packet in 
the receive queue is dequeued, regardless of which task sent it. 
If a sender task is specified, only a packet sent by that task is 
dequeued . 
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Table 4-4 The Send/Receive Data Directive 



Di rective 
Name 



Di rective 
Call 



Notes 



Send Data 



SDAT$ 



Sends a 13(10) word 
buffer to receiver. 



Event flag (if used) 
set when packet queued 
to receiver. 



Receive Data 



RCVD$ 



Error if no data 
packets queued. 



Receive Data 
or Ex i t 



RCVX$ 



Exit if no data 
packets queued. 



Receive Data 
or Stop 



RCST$ 



Stop if no data 
packets queued. 



Synchronizing Send Requests with Receive Requests 

You can use event flags for synchronization. The event flag 
is specified by the sending task. This event flag is set when the 
data packet has been queued to the receiving task. Therefore, a 
global or group global event flag may be used to unblock a 
receiving task which is active and waiting for the event flag to 
be set. 

You can also use an AST for synchronization. To request 
entry into an AST routine whenever a data packet is received, use 
the Specify Receive Data AST directive (SRDA$) . Typically, this 
directive is issued at the beginning of task execution. From that 
point on, the AST routine is entered when the first data packet 
has been placed in the task's receive queue. Only one receive 
data AST is queued, even if more than one data packet is received 
at a time. Therefore, you should keep receiving until you get a 
no data packets queued error to ensure that you have received all 
of the data packets in the queue. 
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After the run, use ASTX$S to exit from the AST routine. 
After exiting from the AST routine, the AST routine will be 
entered again if a new data packet is received. This continues 
until the task exits, or until receive data AST's are canceled, 
using the Specify Receive Data AST directive (SRDA$) with no AST 
routine specified. It is also possible to temporarily disable all 
AST recognition using the Disable AST Recognition directive 
(DSAR$). 

In addition, you can use the task control directives for 
synchronization. Table 4-5 summarizes the various synchronization 
techniques which might be used. Keep in mind that a Receive Data 
directive (RCVD$) causes an error condition directive, which is 
inconsistent with task state (DSW = -8, IE. ITS) if there is no 
data packet in the receive queue. Receive Data or Stop (RCST$) 
and Receive Data or Exit (RCVX$) , on the other hand, cause the 
task to stop or exit, respectively, if there is no data queued. 
For further information about possible synchronization problems, 
see the writeup on the Receive Data directive (RCVD$) in Chapter 5 
of the RSX-11M/M-PLUS Executive Reference Manual. 



Table 4-5 Methods of Synchronizing a Receiving Task 
(RECEIV) with a Sending Task (SEND) 



Method 

RECEIV issues a 
Wait for or a 
Stop for Event 
Flag directive 
followed by a 
receive directive 
SEND uses that 
(common or group 
global) event 
flag in its Send 
directive . 



Advantages 

Low system schedul- 
ing overhead. 



Di sadvantages 

Requires care in 
initializing and 
setting flag. (See 
Examples 4-3 and 
4.4.) 



RECEIV issues a 
Suspend or a 
Stop directive 
followed by a 
Receive directive. 
SEND issues a 
Send directive 
followed by a 
Resume or an 
Unstop directive. 



Does not require an 
event flag. 



Possible problems 
in sequence of 
Suspend or Stop, 
and Resume or Unstop 
if the Resume Unstop 
is issued before the 
receiver suspends or 
stops . 
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Examples 4-3, 4-4, and 4-5 show the use of Send and Receive 
directives by a pair of tasks. Examples 4-3 and 4-4 use an event 
flag for synchronization; Example 4-5 uses Receive Data or Stop 
along with Unstop for synchronization. The notes below are keyed 
to Example 4-3. Note 1 refers to SEND1 and RECVl. Notes 5, 6 and 
7 refer to SEND1. Notes 2, 3, 4 and 8 refer to RECVl. 

Q RECVl must be run first, or else the event flag will 
already be set by SEND1 to indicate that a data packet has 
been sent. RECVl will clear the flag and wait for it to 
be set again, and won't realize that a data packet is 
already queued to it. 

Q Initialize the message counter. You will receive and 
display three messages and then exit. 

Q Initialize the event flag. 

Q Wait for the flag to be set after SEND1 sends the data 
packet, placing it in RECVl's receive queue. 

Q Get the data to be sent. 

Q Send the data and set event flag 33. when the data packet 
is queued to RECVl. 

Q SEND1 exits. 

Q Receive data from anyone. 

Q Display a header and the data sent. Skip the first two 
words (four bytes) of the buffer, which contain the name 
of the sender task in Radix-50 format. 

Q Decrement the message counter. Branch back to clear the 
event flag and receive again if you have not yet received 
three messages. If you have, display a message and exit. 
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• [ 



1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 



♦ TITLE RECV1 
♦I DENT /Ol/ 
♦ ENABL LC 

FILE RECU1 *MAC 



y Enable lower case 



<e*g*y SEND!)* It prints the data on Ti:» Then it 
waits for another data packet* It does this until it 
has received 3 messages and then exits* 



5 
y 

5 This task receives data from any sender task 
f 
y 

y 
y 

y This task synchronizes with its sender through an 

5 event flag* 

r 

? As s e m b .1. e a n d t a s k -- b u i Id i n s t r u c t i o n s ♦ 
y 
y 
r 
y 
y 

9 

y - 



MACRO/LIST LB?Clyl.IPROGMACS/LIBRARYydevU'ufd:iRECVl 
LINK/MAP RECV1 ?LBi 11 y 1 3PR0GSUBS/LIBRARY 

Install and run instructions* RECv\1. must be installed 
and run before running SEND1* 



♦HCALL 
* MCALL 



CLEF*C*WTSE*C»RCVD*C»EXIT*S 5 Systc 
TYPE y DIRERR y Supplied macros 



icros 



y 

EFN « 

9 

rbuff: 

9 



y 



33* 



♦ BLKW 



15* 



♦ ENABL LSB 



y Event flag 

y Receive buffer 

y Enable local symbol 
y blocks 



START** MOV 



#3 y R5 



AGAIN ♦ CLEF$C EFN 



WAIT 



i t 



Initialize message 

counter 
Initialize 
synchronizing flag 
y Branch on directive ok 
< ERR OR INITIALIZING FLAG> y Display 

y error message and 
EFN y Wait for a send 

3$ y Branch on directive ok 

<WAIT DIRECTIVE FAILED> y Display error 
y message and exit 
y We get here when the flag is set 

3** RCVD*C y RBUFF 9 Receive from anyone 

BCC 5$ y Branch on directive ok 



wait: 



BCC 

DIRERR 

WTSE*C 

BCC 

DIRERR 



Example 4-3 Synchronizing a Receiving Task Using Event Flags 

(Sheet 2 of 3) 
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If a task runs and then exits with data packets in its 

receive queue, those unreceived data packets are flushed from the 

queue on exit. Therefore, if SEND1 sent four messages before 
RECV1 was run, the fourth message would be lost. 

If you want to run the tasks in Example 4-3 in any order, 
RECV1 must be modified to receive data packets on startup if SEND1 
has already sent data. The process gets complicated because SEND1 
may have already sent several data packets. It's also possible 
that event flag 33. was left set by someone else. In that case 
the Receive directive will fail, but you should not abort. 

Example 4-4 shows the modifications which must be made to 
Example 4-3 to allow the tasks to be run in any order. The 
following notes are keyed to Example 4-4. 

Q Use a flag word (BEFORE) to distinguish whether you are 
working on messages sent before or after RECV1 starts up. 
Note that RECV1S must be installed as RECV1, since SEND1 
sends to RECV1. 

Q Check to see if the event flag is set on startup. If it 
is set, issue a Receive. If SEND1 has been run one or 
more times, the Receive will succeed. If SEND1 has not 
yet been run, the flag was set by another task and the 
Receive will fail. 



If the flag was not set, SEND1 hasn't sent any messages 
before you started. Clear the BEFORE flag, because a 
Receive failure after the flag is set again is a fatal 
error . 

In the case of a receive failure, check to see if you are 
receiving data packets that are sent before RECV1 started 
up. If you are, you know you have received all data 
packets already queued up before RECV1 started executing. 

If BEFORE is clear, there was a failure after receiving 
all data packets sent before RECV2 started up, so display 
an error message and exit. 
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8 

9 
10 
11 

.1.2 
13 
.1.4 
15 
16 
1 7 
.1.8 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 

r3.i. 

32 
33 
34 
35 
36 
L37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 



♦TITLE 
♦I HE NT 
♦ENABL 



RECV1S 

/Ol/ 

LC 



9 Enable lower esse 



FILE RECV.1S*MAC 



r + 

9 
f 

9 
9 
9 
9 
9 

9 This task synchronizes with its sender through 



This task receives data from sny sender task 
< e . g ♦ SEND 1 ) ♦ I t p r i n ts the data or. T I ! ♦ Then 
waits for another data packet* It exits after 
r e c e i v i n £5 a n d d :i. s p 1 a « i n g 3 mess a g e s ♦ 



it 



>n 



9 
9 

5 
5 

v 

9 
9 
9 
9 
9 

9 Install and run instructions I R EC VIS must be installed 
9 under the name RECV1 to work with SENDl ♦ 

9 ■- 

♦MCALL CLEF*C>WTSE*C»RCVD*C»EXIT*S y System maci 
<• MCALL TYPE'y DIRERR y Supplied macros 



event flag* Because of this synchronization* and the 
e a r e w e t a k e o n s t a r t u p t o g e t m e s s a g e s a I r e a d y 
sentv the tasks can be run in any order y with any 
r e I a t i v e p r i o r i t i e s ♦ 

A s s e in b 1 e a n d t a s k - b u i I d i n s t r u c t i o n s ♦ 

MACRO/L 1ST LB t L" 1 y 1 1 PROGM ACS/L I BRARY y de v i L" uf d 3 RECU 1 S 
LINK /MAP RE C VIS y LB * C 1 y 1 3PR0GSUBS/LIBRARY 



y 

EFN 

9 



33* 



9 Event flag 



"Before" flagy used to keep track of whether we are 
receiving messages sent before RECM1 started up* If 
the event flag is set at startup time? keep receiving 
until we get a failure* We then wait until the flag is 

means receiving messages sent 
ns finished receiving them* 

5 Assume there are messages 



set to receive again* 
b e f o r e s t a r t u p y 



BEFORE ♦ 
R BUFFI 
y 

y 

START ♦ 



.WORD 

* BLKW 



1 

15* 



♦ ENABL LSB 



y Receive buffer 



y Enable local symbol blocks 



MOV #3yR5 ? Message counter 

CLEF$C EFN 5 Initialize synchronizing 

9 flag 

BCC 1$ y Branch on directive ok 

DIRERR <ERR0R INITIALIZING FLAG> y Display 

y error message and exit 



Example 4-4 A Receiving Task Which Can be Run Before or After 

the Sender (Sheet 1 of 3) 



173 



USING DIRECTIVES FOR INTERTASK COMMUNICATION 



Run Session 

>INS/TASK....NAME : RECV1 RECV1S 
>RUN SEND1 

TYPE A LINE OF TEXT v 26 CHARACTERS OR LESS 
1111 11 
>RUN SEND1 

TYPE A LINE OF TEXT* 26 CHARACTERS OR LESS 
£'2222 22222 
>RUN RECV1 

DATA RECEIVED BY "RECVl"? 
1111 11 

DATA RECEIVED BY "RECvl'J 

' :> 222222222 

RUN SEND1 

TYPE A LINE OF TEXT* 26 CHARACTERS OR LESS 
33333 

DATA RECEIVED BY "RECVl't 
33333 

"RECVl" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 



Example 4-4 A Receiving Task Which Can be Run Before or After 

the Sender (Sheet 3 of 3) 



Example 4-5 uses Receive Data or Stop in the Receiver and 
Send Data followed by Unstop in the sender. These tasks can be 
run in any order. The potential synchronization problems are 
considerably easier to deal with when using this technique of 
synchronization. The technique will be explained first as it 
applies to the case of running RECV2, before you run SEND2. A 
discussion of the other possibilities will follow. Notes 2, 3 and 
4 refer to SEND2. Notes 1, 5, 6, 7, 8 and 9 refer to RECV2. 

Issue a Receive Data or Stop directive. If there is no 
data packet queued, RECV2 stops and must be unstopped by 
SEND2. If, on the other hand, there is a data packet 
queued, you would want to receive it. The DSW equals 
IS. SET (+2) if the task was stopped and then unstopped, and 
equals IS.SUC(+1) if a data packet was received. If RECV2 
is run first, stop. 

SEND 2 gets the data and sends it. You do not need to 
specify an event flag in the Send Data directive since you 
use Stop/Unstop for synchronization. 



o 



e 
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If SEND2 is run two or three times before RECV2, any data 
packets already sent are received and displayed. In the case of 
two sent, the third RCDS$ will cause RECV2 to stop until SEND2 
sends a third packet and unstops it. In the case of three packets 
already sent, RECV2 will receive all three and then exit. 

As in Example 4-4, if SEND2 sends more than three packets, 
any additional packets will be lost because the receive queue is 
flushed when the task exits. 
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1 

2 
3 
4 
5 
6 
7 
8 
9 
10 
11 

13 
1.4 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 



♦ TITLE RECV2 

♦ I DENT /Ol/ 
* ENABL LC 



y Enable lower case 



$ FILE RECV2*MAC 



y This task receives data from another task* It prints 

v the data? along with a header? on TI** Then it waits 

y for another data packet? continuing this until it has 

y received 3 messages * 
J 

f This task synchronizes with its sender using RCST$* 

y Because of this synchronization y the tasks can be run 

v in any order? with any relative priorities* 

? Assemble and task build instructions* 
5 

5 MACRO/LIST LB I C 1 y 1 3PR0GMACS/LIBRARY y dev : Cuf dIIRECV2 

y LINK/MAP RECV2?LBi C 1 y 1 3PR0GSUBS/LIBRARY 

y 

y Install and run instructions: RECV2 must be installed* 



RBUFF 



♦ MCALL 
♦ MCALL 

*BLK'W 

* ENABL 



RCST$CyRCVD$CyEXIT$S r System macros 
y Supplied macros 



TYPE? DIRERR 
.1.5* 
LSB 



y Receive buffer 

y Enable local symbol 
y blocks 



START? MOV #3yR5 y Set up message counter 

RECEIV* RCST$C yRBUFF y Receive from anyone 

BCC 5$ 5 Branch on directive ok 

DIRERR <RECEIVE DIRECTIVE FAILED IN "RECV2 U > 

5 Display error message 
y and exit 

y Successful receipt or unstopped by another task* First 

y check for unstopped after being stopped y in which case 
y we have to receive the data 

■5*: 



6$i 



CMP 
BNE 

RCVD*C 
BCC 

DIRERR 

TYPE 

TYPE 
SOB 



TYPE 

E.XIT$S 
♦ END 



y Were we stopped due to 
y no data 

y If not? we have a data 
y packet 

? Now get the packet 
y Branch on directive ok 
<RECEIVE DIR FAILED AFTER "RECV2" UNSTOPPED.": 
y Display error message 
y and exit 
<DATA RECEIVED BY "RECV2 B J> 



$DSWy#IS*SET 
6$ 

yRBUFF 
6* 



#RBUFF+4y#26* 
R5y RECEIV 



y Display 
y text and 
y data sent 
Decrement message 
counter* Receive again 
if haven't received 3 
yet 



< " RECV2 ' 



START 



HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 
y Type exit message 
y Exit 



Example 4-5 Synchronizing a Receiver Task Using RCDS$ 

(Sheet 2 of 3) 
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Using Send/Receive Directives for Synchronization 

If you want to pass data as well as notify another task of 
the occurrence of an event, the send/receive directives can be 
used to perform this double function. The receiving task can 
synchronize with the event using any of the techniques listed in 
Table 4-5. 



Slaving the Receiving Task 

Normally, a task runs under the UIC and the TI: of its 
initiator, the operator issuing the RUN command, or the task 
issuing the Request Task directive (RQST$). A receiver task which 
is run from the same terminal as the sender is assigned the same 
UIC and TI: as the sender. However, if the receiver task is run 
from another terminal or by a different user, it's UIC and/or TI: 
may be different from that of the sender. Also, a receiver might 
receive data from several different tasks initiated at several 
different terminals. 

If you want to have the receiver task take on the UIC and the 
TI: of the sender each time data is received, the receiver task 
can be built as a slaved task. The advantages of this approach 
are that the receiver acquires the same privileges as the sending 
task and can do I/O directly to the sending task's terminal 
(through TI:). To build a task as a slaved task, either 
task-build or install with the /SLAVE qualifier. 
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PARENT 



OFFSPRING 



SPAWN OFFSPRING 



COMMAND LINE 




EXIT, EXIT 
WITH STATUS, 
OR EMIT 
STATUS 



EVENT FLAG AND/OR 
AST ROUTINE 



OFFSPRING STATUS 



TK-7745 



Figure 4-1 Parent/Offspring Communication Facilities 



Additional directives are provided for parent/offspring 
support. The Send Data, Request, and Connect directive combines 
the functions of the three separate directives (Send, Request, 
Connect) into a single directive. This is similar to Spawn, but 
sends a 13. word data packet rather than a 79. byte command 
line. It also only sends data and connects if the task is already 
active. Spawn is rejected if the task is already active, unless 
the task is a Command Line Interpreter (CLI) . 

Two other directives are provided to allow chaining, or 
passing a parent/offspring connection from an offspring to another 
task. Chaining is discussed in more detail later in this module. 
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Table 4-7 Comparison of Parent Directives 



Characteristic 

Can be used for 
offspring which 
is not yet active 

Can be used with 
offspring which 
is already active 



Can pass data (or 
command) to off- 
spring* 

Can be used to 
pass commands to 
a Command Line 
Interpreter (CLI) 



Spawn 



Yes 



No, except 
if offspring 
is a Command 
Line Inter- 
preter (CLI) 

Yes (up to 
79. bytes) 



Yes 



Connect 



No 



Yes 



Send, Request 
and Connect 

Yes 



Yes 



No 



No 



Yes (13. words) 



No 



* If a parent/offspring relationship is established via Connect, 
the tasks can exchange data using Send/Receive. The table above 
indicates that the passing of data from parent to offspring is not 
a capability of the Connect directive, in and of itself. 

LEARNING ACTIVITY 4-1 
Chapter 4 of the RSX-11M/M-PLUS Executive 
Reference Manual contains a good discussion 
of the Parent/Offspring directives and gives 
a number of possible uses for them. The 
various uses will not be discussed anywhere 

Read Sections 4.1, 4.2, and 4.3 in the 
RSX-11M/M-PLUS Executive Reference Manual for 
a discussion of the Parent/Offspring 
directives and examples of their use in 

iilliM^ 
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Example 4-6 shows a task which spawns PIP to display a directory 
at TI:. The following notes are keyed to the example. 



Q The command line to be passed to PIP. We include the 
three-character command name to be consistent with the way MCR 
passes commands if a utility command is typed to MCR. 

Q Display startup message. 

Q Spawn ...PIP. Event flag 1 will be set when ...PIP exits or 
emits status. EXSTAT is the address of the eight-word status 
block (only the first word is used) . CMD is the starting 
address of the command line and LEN is its length. 

Q Wait for event flag 1 to be set when ...PIP exits or emits 
status. Notice that this is a local event flag, local to this 
task, which is cleared by the Executive when the task is 
spawned and set by the Executive when the spawned task exits 
or emits status. 

Q The high order byte of the exit status code may contain 
unexpected data. Therefore, clear that byte before converting 
the code to signed decimal for display. 

Use $EDMSG to produce a status message. Display the message 
and then exit. 

O ON THE RUN SESSION - The first run session shows a successful 
exit by ...PIP, the second one shows ...PIP aborted by an 
operator. Note the different status codes. 



NOTE 

On an RSX-11M system, an attempt to spawn 
...PIP will fail if ...PIP is already active. 
This works diffently from initiating PIP from 
MCR, where an attempt is made to install the 
task ...PIP under the name PIPTnn if ...PIP 
is already active. A solution to this 
problem is to spawn CLI... (the current 
CLI), ...DCL (DCL) or MCR... (MCR) and send 
it the command line. It will in turn start 
up the appropriate PIP task under ...PIP or 
PIPTnn, as if the command was typed in by an 
operator. See section 4.4 (on Spawning 
System Tasks) of the RSX-11M/M-PLUS Executive 
Reference Manual for additional information. 
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53 


r Error 


h3ndl ing 


code 


54 


errid: 


DIRERR 


<ERR0R 


55 


errii: 


10 ERR 


#.T0SB? 


5* 


ERR2 : 


DIRERR 


<ERROR 


57 


ERR 3 : 


DIRERR 


<ERROR 


59 


ERR4D* 


DIRERR 


<ERROR 


59 


ERR4I * 


IOERR 


#.TOSB.* 


60 




♦ END 


START 


Run 


Session 







Display error message and exit 
TING STARTUP MESSAGE.** 



>RUN SPAWN 

SPAWN IS STARTING AND WILL SPAWN PIP 

Directory DDI : 1:305? 301 3 
B-MAR-82 12 5 15 



W*MAC?1 
A.1. ♦MAC? 2 
A ♦ MAC v 1 



1* 
1* 
1. 



20-MAY-81 13:04 

09- DEC-80 16:58 

10- JUN-81 15:21 



08-SEP-81 li:20 



SPAWN ♦ MAC 9 2.2. 1* 
Total 127 ♦ /I 29 ♦ blocks in 25* files 
SPAWN REPORTING: PIP EXITED* EXIT STATUS WAS !♦ 



>RUN SPAWN 

SPAWN IS STARTING AND WILL SPAWN PIP 



D i rectory DB 1 * Z 305 9 30 1 .1 
B-MAR-82 12:i5 



20-MAY-81 13:04 

09- DEC-80 16:58 

10- JUN-81 15:21 



W*MAC?1 !♦ 
A.UMACJ2 1» 
A ♦MAC?! !♦ 
DCL> ABORT/TASK • * .PIP 

A9.MAC512 4* 21-MAY-81 13:50 

12:i5:i5 Task "♦♦♦PIP" terminated 

Aborted via directive or CLI 
And with pending I/O reauests 

_ spawn reporting: PIP EXITED* EXIT STATUS WAS 4* 



Example 4-6 A Task Which Spawns PIP (Sheet 2 of 2) 
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©[ 



©[ 



3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 



♦TITLE GSPAWN 
♦ I DENT /Ol/ 
♦ENABL LC 



5 Enable lower esse 



r + 



FILE GSPAWN* MAC 



This task prompts 3t ti* for 3 task name and command 
line* then spawns the specified task and passes it the 
command line* After that it waits until the offspring 
task exits and displays its exit status* 

Assemble 3nd task-build instructions* 

MACRO/LIST LB * C 1 y 1 3PR0GMACS/LIBRARY r dev I Cuf d II GSPAWN 
L INK/MAP GSPAWN y LB ♦ 1 1 y 1 3 PROGSUBS/L I BR AR Y 

Run instructions* The ri3me of the task to be spawned 
must be typed in using all upper case characters* 

♦MCALL SPWN*SyEXIT*SyEXST$yDIR*yWTSE$C 5 System 

y macros 

♦ MCALL INPUT y TYPE y DI RERR y Supplied macros 

y 

y I/O buffer ~ initialize first 6 bytes to blanks to pad 
y short task names 
BUFFER* * ASCI I / / 



♦ BLKB 
TSKNAM * ♦ BLKW 
bomb: EXST* 



BUFF* 

fmt: 



74* 

2 

EX*SEV 
80* 



y Task name in RAD50 
y Directive for fatal 
? error 

♦ BLKW 80* y Output buffer for exit 

y status display 
*ASCIZ /%N%10STASK EXITED* STATUS WAS %D*%N/ 



♦ EVEN 

exstat: *blkw 



8* 



* ENABL LSB 
START ♦ TYPE <TASK NAME?!: 
INPUT #BUFFERy#80. 



y Status block 



y Display prompt 
? Get input (buffer addr 
y returned in RO) 
y Branch on directive ok 



BCC 1$ 
TYPE <INPUT FROM TIJ FAILED> 
DIR* BOMB y Fatal error 



Example 4-7 A Generalized Spawning Task (Sheet 1 of 3) 
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Run Session 



>RUN GSPAWN 
TASK NAME? 
♦ . .PIP 

COMMAND LINE (79 CHARACTERS OR LESS) ? 
PIP *.D IS/LI 

Director y D B 1 1 I." 3 5 •> 3 1 1 
8~SEP~81 15 ♦ 09 

FRIENDSHIP'S J 2 1* 10-AUG-81 1.1.:13 

F R I E N D S N I... ♦ D I S J 2 .1. ♦ 31-AUG-81 1.1. J42 

Total of 2 ♦/!()♦ blocks in 2» files 



TASK EXITED ♦ STATUS WAS 1* 



>RUN GSPAWN 
TASK NAME? 
CLI. ♦ ♦ 

COMMAND LINE (79 CHARACTERS OR LESS)? 
DIRECTORY **MAC 



Directory DB 1 : C 305 ? 30 1 .'.'I 
8 -SEP -81 15 t .1.0 



W.MACJ1 1 
A1.MACJ2 1 
A*MAC?1 1 
A9 ♦ MAC y .1.2 4 
FORMAT ♦ MAC P 34 6 
PROG Y. MAC M 1 
PR0GZ*MACJ1 1 
RAY ♦ MAC J 1 4 
DCL> ABORT/TASK D I R 
PROGX . MAC J 6 
CM AC? 5 
A2*MACJ2 
C2*MACr 1 



20- MAY-81 

09- DEC-80 

10- JUN-81 
2.1. -MAY-SI 

21 - AUG- 81 
30- JAN -81 
30-JAN-81 
30~~JAN~81 



30-JAN-81 
21 -MAY-SI 

21-MAY-81 
21-MAY-81 
Task "DIRT11" terminated 
Aborted via directive or CLI 
And with pending I/O requests 



.1.3 i 04 
16 i 58 
15 J 21 
13 i 50 
1 1 : 53 
.1.4 1 27 
14J30 
14J39 

14M2 
10 J 01 
10J04 
10J04 



TASK EXITED ♦ STATUS WAS 4* 



Example 4-7 A Generalized Spawning Task (Sheet 3 of 3) 
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Chaining of Parent/Offspring Relationships 

An offspring can chain or pass on its parent/offspring 
connection to another task. In that case the connection between 
the parent and the offspring which passes the connection is 
broken. In its place, a connection is made between the parent and 
the new offspring. 



Figure 4-2 shows the difference between an offspring spawning 
another task versus chaining its connection to another task. Note 
that with Spawn, the connection between the parent and the first 
offspring still exists, and a new connection is established 
between the first offspring and the new offspring. 

Table 4-10 summarizes the directives which can be used to 



chain parent/offspring relationships. Request and Pass Offspring 

- - ... . _ function, in that it 



command line. Send 



Information (RPOI$) is similar to Spawn 
starts up the task and can pass a 79. byte 
Data, Request, and Pass Offspring Control Block (SDRP$) is similar 
to Send Data, Request and Connect, in that it sends a 13. word 
data packet, and executes successfully even if the task is already 
active . 



TASK 2 
SPAWNS 
TASK 3 



TASK 2 REQUESTS 
AND PASSES OFFSPRING 
INFORMATION 



BEFORE 



TASK 1 



TASK 2 



AFTER 



BEFORE 



AFTER 



TASK 1 



TASK 1 



TASK 2 



TASK 1 



TASK 2 



TASK 2 



TASK 3 



TASK 3 



NOTE: EACH ARROW SHOWS A PARENT/OFFSPRING CONNECTION. 
THE ARROW STARTS AT THE PARENT AND POINTS TO THE OFFSPRING. 



Figure 4-2 Spawning Versus Chaining 
(Request and Pass Offspring Information 
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The following notes are keyed to Example 4-8. 

Q Use RPOI$ instead of SPWN$. No event flag is needed nor 

is a status block set up since this task won't receive 

status from ...PIP. RP.OAL specified means that all (in 

this example there is only one) parent connections are 
passed on. A connection is established between the parent 

of PASSIT (GSPAWN) and ...PIP. The connection between 

GSPAWN and PASSIT is broken. 

Q Display a message and exit. You don't need to use $EDMSG 
because this task doesn't receive exit status. 

Q Exit with a status of 10., to make it easy to tell whether 
the status is from this task or from ...PIP. Note in 
SPAWN that EXIT$S is used, which results in a success code 
(+1) being sent as the exit status. 

Q On The First Run Session (GSPAWN spawns PASSIT) - The exit 
status from ...PIP is returned directly to GSPAWN. 

Q On The Second Run Session (GSPAWN spawns SPAWN) - The exit 
status from ...PIP is returned to SPAWN, then SPAWN 
returns its own exit status to GSPAWN. 

If you wish to chain the connection from only one of several 
parents, specify a single task, and do not specify RP.OAL in the 
RPOI$ directive call. If RP.OAL is not specified and no task is 
specified, then no connections are passed. This might be useful 
to request a task and send 79. bytes of data when a connection is 
not needed. 
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Run Session 

>INS PASS IT 
>RUN GSPAWN 
TASK NAME? 
PASS IT 

COMMAND LINE (79 CHARACTERS OR LESS) ? 

PASSIT IS STARTING AND WILL REQUEST PIP 
PASS IT HAS REQUESTED PIP AND WILL NOW EXIT 

Directory DDI ♦ £305*30.1 3 
8-MAR-82 1.5 J 22 

W. MAC 51. 1. 20~MAY~81 13104 

A I.MAC 5 2 1. 09--DEC-80 16:58 



SPAWN* MAC J 1 4. 08--SEP-81 13*32 

Tot3l of 13 ./66* blocks in 15 ♦ files 



TASK EXITED. STATUS WAS 1* 



>RUN GSPAWN 
TASK NAME? 
PASSIT 

COMMAND LINE (79 CHARACTERS OR LESS)? 

PASSIT IS STARTING AND WILL REQUEST PIP 
PASSIT HAS REQUESTED PIP AND WILL NOW EXIT 

Di rectory DDI i £305 y 30:1. 3 
8-SEP-81 15:23 



W.MAC51 
A1.MACJ2 
A ♦ MAC r 1 
A9.MACJ12 
15 J 24: 10 



1* 20-MAY-81 13: 04 

1. 09-DEC--80 16:58 

1. 10-JUN--81 15 J 21 

4. 21-MAY--81 13:50 
Tssk " ♦ ♦ ♦ P I P " te rm i ns t ed 
Aborted via directive or CLI 
And with pending I/O reauests 



TASK EXITED. STATUS WAS 4. 



Example 4-8 An Offspring Task Which Chains Its 
Parent/Offspring Connection to PIP (Sheet 2 of 3) 
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Other Parent/Offspring Considerations 

Retrieving Command Lines in Spawned Tasks - Use the Get MCR 
Command Line directive (GMCR$) . The passed command is returned, 
beginning at offset G.MCRB within the DPB for the GMCR$ directive. 
Therefore, if you use the $ form of the directive and if the DPB 
starts at location DPB1, the first character of the command line 
is at location DPB1+G.MCRB. 

Spawning a Utility or other MCR Spawnable Task - Utilities are 
generally installed under task names of the form ...tsk. This 
makes them MCR spawnable tasks, which notifies MCR to spawn 
multiple copies of the task under names tskTnn if the task is 
invoked as an MCR command using the three-character task name 
(e.g. , PIP /LI) . 

Any task is spawnable, but only tasks installed under a name 
of the form ...tsk are spawned as multiple copy tasks by MCR. 
When such a task is invoked by MCR, MCR passes it the entire 
command line, including the three-character task name (e.g., 
PIP /LI). Even if you spawn a utility directly, you should pass a 
command line which includes the three-character task name. This 
maintains compatibility with the format used by MCR to pass 
commands to utilities, and avoids potential problems caused when 
the utility parses your command line. 

On RSX-11M systems, there is a greater chance of getting a 
task already active failure if you spawn a utility directly using 
the name ...tsk, than there is if you spawn MCR... and pass the 
command line which includes the task name. This is due to the 
fact that if a task is spawned directly using ...tsk, the spawn 
attempt fails if the task ...tsk is already active. No attempt is 
made to install the task under the name tskTnn if ...tsk is 
already active, as is the case if you spawn MCR... (MCR) to start 
up the utility. 
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3 
4 
5 
6 
7 
8 
9 
10 
11 

13 
14 

15 
16 
17 
18 
19 
20 
21 



♦TITLE 
. I DENT 
♦ENABL 



SPWNED 

/Ol/ 
LC 



y Enable lower case 



y This task uses the GMCR* directive to get a command 

y line from either Tit or the parent task* It then 

y echoes the command line and does an add or multiply? 

? types out the answer and emits status on exit 

y 

y A s s e m b 1 e a n d 1 i n k i nstr u c t i o n s ♦ 
y 

5 MACRO/LIST LB* CI y 1 :.1PRGGMACS/LIBRARY y dev ♦ Cuf d."ISPWNED 

y LINK/MAP SPWNED y LB ♦ CI y 1 3PR0GSUBS/LIBRARY 

y 

y Install and run instructions* To make this task NCR 

y spawnablev install it under the name ♦♦♦SPW* Commands 

y should be of the form SPW n? where n is a function* 

y The valid functions are 1 (for add) and 2 (for multiply)* 

y — 

♦ MCALL EXST*SyGMCR*yDIR*yQIOW*S y System macros 
♦ MCALL TYPEyDIRERRy I'OERR ? Supplied macros 



23 
24 
25 
26 
27 
28 
29 
30 
3.1. 
32 
33 
34 
35 
36 
37 



GMCR ♦ 
BUFF : 

fmt: 

I0SBJ 
DATA * 
NUM1 1 



NUM2 * 
ANSI 
OP t 



GMCR* 

♦ BLKB 

♦ ASCIZ 

♦ EVEN 

♦ BLKW 

♦ WORD 

♦ WORD 

♦ WORD 

♦ BLKW 

♦ BLKB 

♦ EVEN 



80* 
/%D 



OP 



y DPB for Get MCR Command 
y Line directive 

y u t p u t buffer 
%A ZD ~ %D#/ y Format string 

y I/O status block 

y 1st operand 

y address of operation 

y sign in ASCII 

y 2nd operand 

y answer to operation 

y operand in ASCII 



Example 4-9 A Spawned Task Which Retrieves a 
Command Line (Sheet 1 of 3) 
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Run Session 

>INS/TASK_NAMEJ ♦ ♦ ♦SPW SPWNED 
>MCR SPW 1 
SPW 1 

5 + 2 « 7. 

>MCR SPW 2 
SPW 2 

5 * 2 « 10 ♦ 
>MCR SPW 3 
SPW 3 

© NO OTHER OPERATIONS ALLOWED 



>RUN GSPAWN 
TASK NAME? 
♦ . ♦ SPW 

COMMAND LINE (79 CHARACTERS OR LESS)? 
SPW 1 
SPW 1 

5 + 2 ~ 7* 

TASK EXITED * STATUS WAS 1* 
">RUN GSPAWN 
TASK NAME? 
. . .SPW 

COMMAND LINE (79 CHARACTERS OR LESS)? 
SPW 2 
SPW 2 

5*2= 10* 

TASK EXITED ♦ STATUS WAS .1. . 
Q >RUN GSPAWN 
TASK NAME? 
♦ ♦ ♦ SPW 

COMMAND LINE <79 CHARACTERS OR LESS)? 
SPW 3 
SPW 3 

NO OTHER OPERATIONS ALLOWED 

TASK EXITED* STATUS WAS 0* 



Example 4-9 A Spawned Task Which Retrieves a 
Command Line (Sheet 3 of 3) 
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Table 


4-11 Task 


Abort Status Codes 


Mnemonic 


Value 


Exit 
Status 


lilliiB^ 


S 


• CEXT 


-2(10) 


EX$SUC=1 


Task exited normally 


S 


. COAD 


lllllllllilllllilll 


EX$SEV=4 


Odd address and traps to four 


S 


.CSGF 


2 (10) 


EX$SEV 


Segment fault 


S 


.CBPT 


4 (10) 


EX$SEV 


Break point or trace trap 


S 


.CIOT 


6 (10) 


EX$SEV 


IOT instruction 


S 


.CILI 


8(10) 


EX$SEV 


T 1 1 pa a 1 or rp^prvprl i n c !frnpt'i' r»n 

JL «!. w JL \y 1. J. w w L V w V-4 JL X 1 I* JL V<* w L» JL 1 1 


S 


.CEMT 


10(10) 


EX$SEV 


Non-RSX EMT instruction 


S 


.CTRP 


12(10) 


EX$SEV 


Trap instruction 


S 


. CFLT 


14(11) 


EX$SEV 


11/40 floating-point exception 


b 


. Lbb 1 


16(10) 


EX$SEV 


SST abort - bad stack 


S 


. CAST 


18(10) 


EX$SEV 


AST abort - bad stack 


S 


.CABO 


20(10) 


EX$SEV 


Abort via directive or CLI command 


S 


. CLRF 


22(10) 


EX$SEV 


Task load request failure 


S 


.CCRF 


24(10) 


EX$SEV 


Task checkpoint read failure 


S 


. IOMG 


26 (10) 


EX$SEV 


Task exit with outstanding I/O 


S 


. PRTY 


28(10) 


EX$SEV 


Task memory parity error 


S 


.CPMD 


30(10) 


EX$SEV 


Task aborted with PMD request 


S 


.CINS 


32(10) 


EX$SEV 


Task installed in two different 

iliii^ 
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Other Methods of Transferring or Sharing Data Between Tasks 

If large amounts of data are to be transferred between tasks 
or shared between tasks, two other techniques are available. 
Tasks can use files on mass storage devices. This technique is 
advantageous if really quick transfer is not essential and/or if a 
permanent copy of the data is needed. 

Tasks can also be written to share a data area in memory. 
This technique is particularly useful if transfer time is critical 
and a permanent copy of the data is either not needed at all or is 
not needed until a later time. Both of these techniques are 
discussed in later modules. 

Now do the tests/exercises for this module in the 
Test/Exercises book. They are all lab problems. Check your 
answers against the solutions provided, either in that book or 
on-line files. 

If you think that you have mastered the material, ask your 
course administrator to record your progress in your Personal 
Progress Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, 
return to this module for further study. 
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MEMORY MANAGEMENT CONCEPTS 



INTRODUCTION 

The use of memory management hardware in mapped systems 
permits the use of more physical memory, task relocation, and the 
sharing of data and code. It also offers a memory protection 
feature. This module explains how the memory management hardware 
works and how the software interacts with the hardware. Later 
modules explain the use of memory management for overlays and 
shared regions. 



OBJECTIVES 

1. To list the differences between mapped and unmapped 
systems 

2. To list the advantages of memory management 

3. To use virtual and physical addresses, windows, and 
regions to describe the mapping of a task. 



RESOURCES 

1. RSX-11M/M-PLUS Task Builder Manual , Chapter 2 

2. PDP-11 Processor Handbook , Chapter 6 (optional) 
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GOALS OF MEMORY MANAGEMENT 

The KT-11 memory management unit is a device available on 
medium and larger PDP-ll's. While the 16-bit addressing structure 
of the PDP-ll's limits processors without a memory management unit 
to 32K words of addressing, processors with a memory management 
unit can support up to 128K words, or even as much as 2000K words 
(2 Meg words), depending on the model of the processor. 

In addition to this extension of the processor's addressing 
space, a memory management unit offers other features not 
otherwise available. With memory management, tasks can be loaded 
and executed at different locations in memory without being 
modified in any way. This means that the operating system can 
load a task into any available space within a system-controlled 
partition; therefore a task need not wait until a specific 
location is available. It also means that the Executive can move 
tasks around to make better use of available space (shuffling) . 

Memory management also provides a mechanism for controlling 
tasks' access to memory. Memory areas can be protected: 
unrelated tasks can reside in memory simultaneously and are 
normally prevented from accessing each other's memory. However, 
tasks which do need to share memory locations are allowed to do 
so, under the rules of memory access built into the Executive. 



HARDWARE CONCEPTS 



Mapped Versus Unmapped Systems 

A system which has the KT-11 memory management unit installed 
and enabled is called a mapped system. Otherwise, it is called an 
unmapped system. Small PDP-ll's, such as the PDP-11/03 and 
PDP-11/04 are always unmapped. The KT-11 unit is available as an 
option on some medium sized processors, including the PDP-11/35 
and PDP-11/40. It is a standard feature on large and newer 
processors such as the PDP-11/70, PDP-11/24, PDP-11/23-PLUS and 
PDP-11/44. 

Table 5-1 shows a comparison of unmapped and mapped systems 
on various PDP-ll's. 
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Figure 5-3 shows the layout of a mapped system with 22-bit 
addressing. Twenty-two bits give an addressing limit of 2048K 
words or 4096K bytes. Again, the top 4K words correspond to the 
I/O page. 124K words are used for UNIBUS mapping, which is needed 
when peripheral devices access memory directly (DMA devices) . 
UNIBUS mapping is necessary to convert an 18-bit UNIBUS address to 
22-bit physical memory addresses. This leaves 1920K words of 
physical memory. Again, the Executive, including POOL, usually 
takes 16K words or 20K words, leaving 1904K words or 1900K words 
for tasks. 



PHYSICAL 
ADDRESSES 
(IN OCTAL) 




177777 ^ 



r 



160000 
157777 



TASK 



> 32K WORDS 
OF ADDRESSING 



(28-N)K WORDS < 



AREA 



28K WORDS 
OF 

MEMORY 



DSR 



N K WORDS „ 
(N<20) 



EXECUTIVE 







TK-7747 



Figure 5-1 Physical Address Space in an Unmapped System 
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4K WORDS { 



124K WORDS < 



1920K 

WORDS OF i 
MEMORY 



1904KOR 
1900K WORDS 



16K OR 20K 
WORDS 



I/O PAGE 



RESERVED 
(UNIBUS MAP) 



TASK 
AREA 



DSR 



EXECUTIVE 



PHYSICAL 
ADDRESSES 
(IN OCTAL) 

17777777 

17760000 
17757777 



17000000 
16777777 



2048K WORDS 
OF ADDRESSING 



Figure 5-3 Physical Address Space in a 22-Bit Mapped System 
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On a mapped system, the Task Builder fixes a task's code in 
virtual address space, but the actual mapping of virtual addresses 
to physical addresses is performed at run time by the memory 
management unit. Tasks may be loaded at different physical 
addresses and still run correctly. As you will see later, mapping 
also allows a task to access several separate pieces of physical 
memory. 



VIRTUAL 
ADDRESSES 
(IN OCTAL) 

137777 



VIRTUAL 
MEMORY 



TASK 

8K WORDS 



100000 



PHYSICAL 
MEMORY 



TASK 

8K WORDS 



DSR 



PHYSICAL 
ADDRESSES 
(IN OCTAL) 



140000 
137777 



100000 
77777 



EXECUTIVE 

16K WORDS 





TK-7759 



Figure 5-4 Virtual Addresses Versus Physical Address 

on an Unmapped System 
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The KT-1 1 Memory Management Unit 

Mode Bits - Bit 15 and 14 and bits 13 and 12 of the processor 
status word (PSW) indicate, respectively, the current and previous 
modes of processor operation. The mode may be: 

• Kernel mode (00) 

• User mode (11) 

• Supervisor mode (01). (Supervisor mode is not used on 
RSX-11M, and is available only on 11/45, 11/55, 11/44, and 
11/70.) 

The purpose of having different processor modes is to provide 
for a privileged mode (kernel) where the Executive can execute 
privileged instructions (e.g., HALT), and can manipulate 
privileged locations (e.g., PSW), and a non-privileged and 
protected mode (user) where tasks usually execute. 



Active Page Registers (APRs) - The Active Page Registers (APR's) 
in the KT-11 memory management unit are used to define the mapping 
or correspondence between virtual and physical addresses. On an 
RSX-11M system, one set of eight APRs is used at a time to define 
this mapping. There is one set of APR's used for each processor 
mode; one is used in user mode and another set is used in kernel 
mode . 

At any given time, the set of APRs in use is determined by 
the mode bits in the processor status word. Each APR in the set 
in use maps a specific range of virtual addresses, as shown in 
Table 5-2. The APR can map zero words, if not in use, up to the 
full 4K words, always in even multiples of 32 words. In 
actuality, the hardware may contain additional sets of APRs, but 
they are not used under RSX-11M. 

Each APR consists of two 16-bit registers, a page address 

register (PAR) and a page descriptor register (PDR) . The page 

address register contains a base address used in mapping the 
appropriate range of virtual addresses. 
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All virtual addresses within the main task area are mapped to 
physical addresses beginning at location 00432400(8). This means 
in effect that each virtual address corresponds to an offset from 
location 00432400(8). The page descriptor registers, not 
illustrated, indicate that APRs 0, 1, and 2 map 4K words each, but 
that APR 3 maps only 2K words. 



VIRTUAL 
ADDRESSES 
(IN OCTAL) 



160000 

140000 

120000 

100000 
70000 
60000 

40000 

20000 



VIRTUAL 
MEMORY 



PAR 
APR VALUE 



COMMON 


|4K WORDS 7 


015322 


^^^^^^^^^^^^ 


6 
5 
4 


000000 


000000 


000000 


005124 


TASK 




o 
2 

•14K WORDS 
1 




004724 


004524 


004324 



PHYSICAL PHYSICAL 
MEMORY ADDRESSES 
(IN OCTAL) 



RESIDENT COMMON 



TASK 
AREA 



1532200 



512400 
472400 
452400 
432400 



Figure 5-6 Page Address Registers Used in Mapping a Task 
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In easier terms, virtual address 40000(8) will be located at 
the base physical address. A virtual address 13422(8) bytes above 
that will be 13422(8) bytes above that physical location. The 
base physical address is determined by converting the block number 
in APR 2, 004724(8), to the physical address 00472400(8). (Recall 
that a block of memory is 100(8) bytes.) Therefore, address 
053422(8) is mapped to the location shown below. 

00472400(8) Base physical address 
+ 13422(8) Displacement 



00506022(8) Actual physical address 



Example 2 

Convert the virtual address 165275(8) 

+ + + 

165275(8) =|111|0101010111101| (2) 

+ + + 

7 05275(8) 
APR Offset 

APR 7 = 015322(8) blocks = 01532200(8) Base physical address 

+ 05275(8) Displacement 

01537475(8) Actual physical address 



The memory management unit performs this conversion using an 
adder and a number of internal registers. The conversion is 
performed at extremely fast speeds. Chapter 6 of the 
PDP-11 Processor Handbook discusses this conversion process in 
more detail. 
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Memory management directives can be used to create and 
initialize additional windows while a task executes. Space for 
these additional windows must be allocated in the task header at 
task-build time, using the "WNDWS" option. Memory management 
directives and their use are discussed in Module 8 on Dynamic 
Regions . 



Regions 

A region is a contiguous area of physical memory to which a 
task may get access rights. A region must be contained completely 
within a partition. It can be part of a partition or the entire 
partition . 

There are three types of regions in an RSX-11M system. 

1. Task region - an area in a user-controlled partition or a 
system-controlled partition into which a task is loaded 
and then executes. 

2. Static Common Region - an area in a common type partition; 
e.g., a shared common for data or a shared library for 
code . 

3. Dynamic Region - an area in a system-controlled partition 
which is created dynamically, at run time, using the 
memory management directives. 

A task gets access rights to a region by "attaching" to the 
region. Before the Executive attaches a task to a region, it 
checks its needed access against the protection on the region. 
This is similar to checking file protection before allowing file 
access. If the task passes the check on access rights, then the 
Executive attaches the task to the region by establishing a 
connection between the two. The total amount of physical memory, 
made up of regions, to which a task is attached is called a task's 
logical address space. 

After a task is attached to a region, it actually accesses or 
uses the region by first "mapping" one of its virtual address 
windows to a part or to all of the region. During this process, 
the Executive uses the window and region information to fill in 
the APRs. After this, references in the task to virtual addresses 
in that window map to physical addresses within the region. A 
region does not have to be the same size as a window. Generally 
it is of equal or larger size than the window. 
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VIRTUAL 
ADDRESSES 
(IN OCTAL) 
177777 

WINDOW 
2 



VIRTUAL 
MEMORY 



PAR 
APR VALUE 



WINDOW 
1 



160000 



147777 
140000 



WINDOW 




120000 
100000 

r 63777 
60000 

40000 |_ 
20000 




A 

II 
!l 



COMMON 

(4K WORDS) 


7 


006056 






014764 


LIBRARY (2K WORDS) 


6- 




5 
4 
3 


000000 


000000 


006232 


TASK 
WINDOW 

(13K WORDS) 


2 
1 



006032 


005632 


005432 



PHYSICAL PHYSICAL 
ADDRESSES 



MEMORY 



LIBRARY 



COMMON 



TASK 
REGION 



(IN OCTAL) 



1476400 



605600 



543200 



Figure 5-7 A Task with Three Windows Mapped to Three Regions 



231 



OVERLAYS 



6 
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INTRODUCTION 

Overlays are used to allow a task to be developed and run if 
there is not enough available physical or virtual memory for a 
task. This module explains the various overlay techniques and how 
to use them. 



OBJECTIVES 

1. To determine whether to use a disk-resident or 
memory-resident overlay in a given situation 

2. To construct overlay structures using the overlay 
descriptor language 

3. To write tasks using overlays. 



RESOURCE 

• RSX-11M/M-PLUS Task Builder Manual , Chapters 3 and 4 



235 



OVERLAYS 



CONCEPTS 

A task may be too large to fit in the available memory. This 
may happen because it is larger than the total amount of memory on 
the system. More likely, it is because the task is larger than 
the partition it is to run in, or the available space within the 
partition. The partition is probably used by other tasks at the 
same time; therefore, the available space may be considerably 
less than the full partition. 

For example, a 20K word task may have to fit in 15K words of 
memory. The task can use overlays and load only portions of the 
code at a time, and use just 15K words of memory. 

Typically, the pieces which overlay each other contain 
subroutines. As an example, consider a task with main code and 
two subroutines, G and H, which overlay each other. The main code 
calls subroutine G first, causing G's code to be read into memory. 
Later, the main code calls subroutine H, causing H's code to be 
read into the same memory locations, overlaying subroutine G. If 
the main code later calls G, G's code overlays subroutine H. As 
the task executes, overlaying is performed whenever necessary. 
You can choose to have all loading of overlay segments done 
automatically, or you can load them manually with specific calls 
to a loading routine. , 

In addition to physical memory limitations, tasks on PDP-11 
systems have virtual memory limitations. As discussed in the last 
module, a task can only use a maximum of 32K words of virtual 
addresses at a time. A task may require more than 32K words of 
physical and also virtual memory. For example, a task may need 
40K words of physical memory, exceeding the virtual addressing 
limit. This means that the task can't address all of its code. 
Overlays loaded from disk permit this task to run in 32K words or 
less of physical memory, and allow all of the code loaded at any 
given time to be addressed. Therefore, 32K words of code or less 
are loaded and addressed at any one time, satisfying the virtual 
address limit. 

Another method is to use special kinds of overlays. With 
these, all 40K words of code can be loaded into memory, but the 
task maps only 32K words of code at a time. This means that the 
task stays within the virtual addressing limits even though it 
uses 40K words of physical memory. 

These special kinds of overlays are called memory-resident 
overlays. They overlay by remapping, rather than reloading, code 
into memory. 
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Main Segment 
PROG calls: 
SUB1 calls: 
SUB 2 calls: 
SUB 3 calls: 

Segment 

PROG 

SUB1 

SUB 2 

SUB 3 

A 

B 

C 

D 

E 

Total 



PROG 

SUB1, SUB2, SUB 3 
A, B 
none 
C r D f E 

Si ze 

in Words 

4K 
2K 
3K 
IK 
IK 
2K 
IK 
2K 
IK 

17K 



Example 6-1 Description of an Overlaid Task 
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STEPS IN PROGRAM DEVELOPMENT USING OVERLAYS 

Use the following steps to develop a task which uses 
overlays . 

1. Assemble each module, producing an .OBJ file for each 

2. Use the editor to create an overlay descriptor file 
(defines the overlay structure for the Task Builder) . 

3. Task-build using the overlay descriptor file as the input 
file . 



THE OVERLAY DESCRIPTOR LANGUAGE (ODL) 

The overlay descriptor language (ODL) is a fairly simple 
language which is used to define the overlay structure for the 
Task Builder. Statements are placed in a text file which has a 
file type 'ODL' (e.g., EXAMPLE. ODL) . This text file is identified 
to the Task Builder as a special file by using the 
/ OVERLAY_DESCRIPTION input file qualifier (/MP in MCR) in the 
task-build command line. 



ODL Command Line Format 

The ODL command lines use the format that follows, 
label: directive arg ument- 1 is t ;comment 
where : 

label - A one- to six-character symbolic, required only 
on an . FCTR directive. 

directive - one of the following: 

.ROOT - indicates the start of the overlay tree 

.END - indicates the end of input 

.FCTR - allows naming of subtrees 

.NAME - allows naming a segment and assigning 
attr ibutes 

.PSECT - allows special placement of a global 
program section (psect) . 
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Examples of ODL 

1. x, the root of a task, calls subroutines y and Z 



.ROOT X-(Y f Z) 
. END 



Explanation: X is the root segment, Y and Z are each 
overlay segments. virtual addresses are assigned to X 
first. Starting after that, Y and Z begin at the same 
virtual address. Either Y or Z (never both) is loaded 
and mapped using those virtual addresses. 



2. Using the information from Example 1, Y calls subroutines 
U and V. 



u 


V 




Z 


Y 


X 



.ROOT X- (Y- (U,V) , Z) 
. END 



Explanation: Add to Example 1. U and V are overlay 
segments which overlay each other. After the last 
address for Y, virtual addresses begin for U and V. 



243 



OVERLAYS 



TYPES OF OVERLAYS 

There are two types of overlays available, disk-resident 
overlays and memory-resident overlays. In fact, both are loaded 
from disk. The distinction is that disk-resident overlays are 
loaded from disk every time they are needed, while 
memory-resident overlays are loaded from disk only the first time 
they are needed. After that, they remain in memory and remapping 
is used to overlay segments as needed. 



Disk-Resident 

Disk-resident overlays are available on all RSX-11M systems. 

An example of a task with a root segment and three disk-resident 
-overlays is shown in Figure 6-3. 

On initial load, only the root segment MAIN is loaded. 
Overlay segments are loaded from disk whenever required. This 
typically occurs when a subroutine in the segment is called. So 
if the root segment MAIN contains a call for subroutine A, for 
example, segment A is loaded from disk prior to the transfer of 
control to A. 

If, after the subroutine returns control to MAIN, a call is 
made to subroutine B, segment B is loaded into memory right over 
segment A. If a call is later made to subroutine C, segment C is 
loaded right over segment B. This loading of overlay segments is 
performed whenever necessary. The subroutines may be called in 
any order, and each subroutine may be called any number of times 
in the course of task execution. 

The same starting virtual address is assigned to all three 

overlay segments, A, B, and C, beginning at the next 32(10) word 

boundary after the code for MAIN. So A, B, 'and C use the same 

virtual addresses and are loaded starting at the same physical 

address. One virtual address window maps the entire task; just 

the code in memory is changed when an overlay is loaded. 

This technique is useful when the entire task is too large 
to fit into the space allowed for it. In the example in Figure 
6-3, a 22K word task runs in 15K words of physical memory. 
Disk-resident overlays are the default overlay type. The ODL 
examples in the previous section all produce disk-resident 
overlays . 
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Memory-Resident 

Memory-resident overlays are available only on mapped 
systems which support the memory management directives. Figure 
6-4 shows the same task as in Figure 6-3, this time with 
memory-resident overlays. On initial load, again only the root 
segment MAIN is loaded. The first time an overlay segment is 
needed it is loaded from disk. However, once a segment is 
loaded, it remains in memory and is not reloaded from disk. 

If subroutine A is called first, overlay segment A is loaded 
and virtual address window 1 is mapped to A. If, after the 
subroutine returns control to MAIN, a call is made to subroutine 
B, then segment B is loaded, but not directly over A. Instead, 
it is loaded into another area of memory, and then virtual 
address window 1 is mapped to B. If a call is later made to 
subroutine C, segment C is loaded into another area of memory, 
and virtual address window 1 is mapped to C. 

The real gain in run time efficiency is made when an overlay 
is needed again. If another call is made to A, overlay segment A 
does not have to be loaded again from disk. It is already 
memory-resident. Therefore, virtual address window 1 is simply 
remapped from segment C to segment A. Any additional overlaying 
is performed by remapping, with no further loading of overlay 
segments necessary. Again, the subroutines may be called in any 
order and each subroutine may be called any number of times. 

The advantage of this approach is that after the first load, 
it is much faster than using disk-resident overlays. However, 
there are no savings in the use of physical memory. In fact, a 
bit more memory is required than with a non-overlaid task. So 
the main use of memory-resident overlays is for overcoming the 
32K word virtual address limit when execution time efficiency is 
important. A 44K word task can use memory-resident overlays if 
there is enough memory available and the time necessary for 
loading disk-resident overlay segments is unacceptable. 

The root segment uses one window, plus each overlay area 
requires a separate window. That means that virtual addresses 
for each overlay segment begin at the starting virtual address 
for the next highest APR, corresponding to a 4K word boundary. 
Notice that A, B, and C all begin at virtual address 60000(8), 
for APR 3 , because MAIN is 9K words long. MAIN uses all 4K words 
in APRs and 1, plus IK word in APR 2 (virtual addresses 40000 (8) 
through 43777 (8) ) . 



247 



OVERLAYS 



VIRTUAL 
MEMORY 



WINDOW 



160000 APR 7 
140000 APR 6 
120000 APR 5 
100000 APR4 
60000 APR 3 
f 40000 APR 2 



WINDOW 




20000 APR1 



APRO 



MAIN 

(ROOT SEGMENT) 
(9K WORDS) 



HEADER AND STACK 



INITIAL LOAD 
AND MAP 



PHYSICAL 
MEMORY 



MAIN 

(ROOT SEGMENT) 



HEADER AND STACK 



Figure 6-4 An Example of Memory-Resident Overlays 
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LOADING METHODS 

There are two loading methods, autoload and manual load. 
With autoload, any necessary loading and/or remapping (in the 
case of memory-resident overlays) is done automatically and is 
transparent to the program. With manual load, the overlay 
segments are loaded by specific user calls to a loading routine. 
Autoload and manual load cannot be mixed in the same task. 



Autoload 

When a call is made to a subroutine in an overlay segment, 
an autoload routine takes control before the transfer to the 
subroutine is made. It checks to find out whether the required 
segment is already loaded, or loaded and mapped. It performs any 
necessary loading and/or remapping. After that, the transfer to 
the called subroutine is made. 

Autoload is path loading, meaning that all segments along 
the path to the required overlay segment are loaded. For 
example, in example 2 in the previous section, with root X and 
subroutines Y, U, V, and Z, if a call from segment X is made to 
subroutine U, both Y and U are loaded. Note that autoload loads 
only overlay segments along the path which are not already 
loaded . 

Autoload is indicated by an asterisk (*) before an overlay 
specification in an ODL line. An asterisk outside a set of 
parentheses applies to all levels inside the parentheses. 

The advantages of autoload are that it is easy to use and 
does not require changes in the source code. One disadvantage is 
that it increases the size of the segments because the autoload 
code plus its data structures must be included in the task. 
Another is that it executes slower than manual load, because the 
autoload code has to check for whether the required segment is 
available or not each time an autoloadable segment is called. In 
addition, autoload must be performed synchronously. See section 
4.1 on Autoload in the RSX-1 1M/M-PLUS Task Builder Manual for 
more information. 
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Manual Load 

With manual load, you must call the subroutine $ LOAD to load 
and/or map any required overlay segment before calling a 
subroutine in that segment. You must also keep track of which 
segments are currently available, to avoid a transfer of control 
to an incorrect segment and to avoid unnecessary calls to the 
loading subroutine. Manual load is not path loading. In Example 
2 of the previous section, if X calls U, it can load just segment 
U, without loading segment Y, unless it is desirable to load 
both. See section 4.2 on Manual Load in the 
RSX-1 1M/M-PLUS Task Builder Manual for more information. 

Manual load is the default loading method. Whenever there 
are no asterisks (*) in an ODL file, manual load is used. 

The advantages of using manual load are that it results in 
smaller overlay segments, is usually more run time efficient, and 
overlay segments can be loaded either synchronously or 
asynchronously. The disadvantages are that you must keep track 
of which overlay segments are loaded and use special code in the 
source program. 

Comparison of a Task With No Overlays, to One With Disk-Resident 
Overlays, and One With Memory-Resident Overlays 

Example 6-1, shown earlier in the module, and repeated below 
for convenience, shows a main program which calls a subroutine, 
which in turn calls another subroutine, etc. Note that the sizes 
shown for the various parts of the task are only approximate. 
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Task-build command: 

LINK/MAP PR0G,SUB1,A,B,SUB2,SUB3,C,D,E 



Partition name ? GEN 

Identification ♦ 01 

Task UIC ? C 305>30 13 

Stack limits: 000254 001253 001000 00512 ♦ 

PRG xfr address? 021254 

Total address windows* 1* 

Task imasfe size ? 17792* words 

Task address limits? 000000 .1.05357 

R-U disk blk limits? 000002 000107 000106 00070* 



*** ROOT SEGMENT? PROG 



R/W mem limits? 000000 105357 105360 35568* 
Disk blk limits? 000002 000107 000106 00070* 



Example 6-2 Map File of Example 6-1 Without Overlays 
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PROG.ODL file: 

.ROOT PROG-* ( SUB 1- ( A r B) , SUB 2 , SUB3- (C , D, E) ) 
.END 

Task-build command: 

LINK/MAP PROG/OVERLAY DESCRIPTION 



Partition name * GEN 

Identification * 01 

Task U1C i IT 305*30 13 

Stack limits: 000260 001257 001000 005:1.2 ♦ 

PRG xfr address? 021260 

Total address windows? 1* 

Task image size * 8800* words 

Task address limits J 000000 042237 

R-W disk hlk limits: 000002 000:1.20 000.1.17 00079* 



EX63*TSK Overlay description: 



Base 


Top 


Length 






000000 


022177 


022200 


09344 ♦ 


PROG 




022200 


032233 


010034 


04124* 


SUB1 




032234 


036237 


004004 


02052* 




A 


032234 


042237 


010004 


04100* 




B 


022200 


036203 


014004 


06148* 


SUB2 




022200 


026247 


004050 


02088. 


SUB3 




026250 


032253 


004004 


02052* 




C 


026250 


036253 


010004 


04100* 




D 


026250 


032253 


004004 


02052* 




E 



Example 6-3 Map File of Example 6-1 With Disk-Resident Overlays 
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PROG.ODL file: 

.ROOT PROG-* I (SUB1-I (A,B) ,SUB2, SUB3-! ( C , D, E) ) 
.END 

Task-build command: 

LINK/MAP PROG/OVERLAY DESCRIPTION 



Parti tion name i GEN 

Identification i 01 

Task UIC * £305*30 13 

Stack limits: 000320 001317 001000 00512* 

PRG xfr address^ 021320 

Total address windows* 3* 

Task image size * 18464* words 

Task address limits: 000000 077777 

R-W disk blk limits: 000003 000122 000120 00080* 



EXDOVRtTSK Overlay description: 



Base 


Top 


Length 




000000 


023077 


023100 


09792* 


PROG 


040000 


050077 


010100 


04160* 


SUB1 


060000 


064077 


004100 


02112* 


A 


060000 


070077 


0.1.0100 


04160* 


B 


040000 


054077 


014100 


06208* 


SUB2 


040000 


044077 


004100 


021.1.2* 


SUB3 


060000 


064077 


004100 


02112* 


C 


060000 


070077 


010100 


04160* 


D 


060000 


064077 


004100 


02 11 2* 


E 



Example 6-4 Map File of Example 6-1 With Memory-Resident Overlays 
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Table 6-1 Comparison of Overlaying Methods (Cont) 



Method 



Task Size 



Memory-Resident 18464(10) words 

of memory 



80(10) blocks 
on disk 

100000 (8) 
virtual 

addresses used 



Advantages and 
Windows Disadvantages 

Advantages 
3 Faster execution 

than disk-resident 
overlays 

Task resident in 
memory at one time 

Disadvantages 
Uses the most 
memory and disk 

IIIIBiB 

May waste virtual 
address space 
Requires space in 
memory to hold 
all of the task 



Table 6-1 compares the three overlaying methods. In addition 
to the various sizes, it lists the advantages and disadvantages of 
each approach. 

Remember that it is also possible to mix memory-resident and 
disk-resident overlays in a task. For example, the first level 
(SUB1, SUB 2 , and SUB 3 ) could be memory-resident, and either or 
both second levels (A, B or C, D, E) could be disk-resident. 
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Include needed modules from FOROTS.OLB in the root segment 
in segment A, and in segment B. You should specify the 
library in each segment which may need it. Otherwise, if 
segment A needs a library module not already included for 
the root segment, the library is not searched again for 
module A. 



An Overlay Example 

Example 6-5 is a simple task with a root segment ROOT and two 
overlay segments, p and Q. The following calling sequence is used 
during the execution of the task. 

ROOT calls p 
ROOT calls Q 



Figure 6-5 shows an overlay tree and a memory allocation 
diagram for this task. 

The code for Example 6-5 is separated into three different 
modules, one for each segment. The source file for the root 
segment ROOT contains the startup code and controls the overlay 
loading by calls to the subroutines. The source file for each 
overlay segment, P and Q, contains the subroutine code. 



OVERLAY TREE 



MEMORY ALLOCATION DIAGRAM 



P Q 
1 1 


P 


Q 


ROOT 


ROOT 



TK-7755 



Figure 6-5 Task With Two Overlay Segments 
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The notes below are keyed to Example 6-5. 

O On initial load only the root segment ROOT is loaded. 

Q With autoload, the call to subroutine P causes the 
autoload routine to load overlay segment P from disk, and 
then transfer control to the subroutine. 

Q Subroutine P displays a message and returns. 

O The call to subroutine Q causes the autoload routine to 
load overlay segment Q from disk over segment P, and then 
transfer control to the subroutine. 

Q Subroutine Q displays a message and returns. 

If another call were added to subroutine Q, the autoload 
routine would check to make sure that overlay segment Q is already 
loaded, and would then transfer control to Q. If another call 
were added to subroutine P, the autoload routine would check and 
find that overlay segment P is not loaded. It would then load 
segment p over segment Q and transfer control . 

To use manual load, use additional code to load the segments 
into the root segment ROOT. Also, modify the . ODL file, omitting 
the asterisk (*) . The files MLROOT. MAC and MLEXDOVR . ODL on the 
tape provided with this course are modifications of ROOT. MAC and 
EXDOVR.ODL for manual load. Check UFD [202,3] for these files. 
See your course administrator if you have difficulty finding them. 
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3 
4 



1 



♦ TITLE Q 

♦ I DENT 
♦ ENABL 



/O.I./ 
LC 



y Enable lower case 



y FILE Q ♦ MAC 



6 
7 
8 
9 
10 
11 
12 
13 
14 
15 



MESi 



r This subroutine displays a message and returns* 



♦ ASCI I 
♦ASCII 
LMES = 

♦ EVEN 



♦ MCALL 



/SEGMENT Q IS NOW LOADED* SUBROUTINE 0/ 
/ IS EXECUTING* / 
■- MES 



GI0W$C 



f Move to word boundary 



y External swstem macros 




RETURN 
♦ END 



QI0W*C 



1 ♦ WVB y 5 y 1 y y y y <MES f LMES y 40> y D i SP I ay 

? message 

y Return 



Run Session 



>RUN EXDOVR 

THE MAIN SEGMENT IS RUNNING AND WILL CALL P* 
SEGMENT P IS NOW LOADED ♦ SUBROUTINE P IS EXECUTING* 
THE MAIN SEGMENT WILL NOW CALL 0* 

SEGMENT Q IS NOW LOADED* SUBROUTINE Q IS EXECUTING* 
THE MAIN SEGMENT WILL NOW EXIT* 



Example 6-5 A Task With Two Overlay Segments (Sheet 2 of 2) 
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Table 6-2 How Global Symbols Are Resolved 



Reference Resolved 

Q is defined A22 A0 

in A0 and B0 Al A0 

R is defined A22 A2 

in A? Al Undefined 



(If autoload, defined through 
an autoload vector.) 

S is defined Al 
in A0 and B0 A21 

T is defined 

in A0 and A21 Symbol multiply defined. 



A0 
A0 
A0 
B0 
B0 

Ambig uo us 
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Subroutine Calls 

With manual load, since the global symbols are resolved 
directly to the virtual address corresponding to the symbol, the 
transfer is directly to the subroutine. The program must ensure 
that the correct overlay segment is loaded before making the call. 
Otherwise, the transfer will transfer control to that virtual 
address in the wrong code, causing unexpected results. 

With autoload, the global symbols are resolved directly for 
calls downward toward the root. This works because path loading 
ensures that the segments along the path closer to the root are in 
fact loaded. The calls to subroutines away from the root are 
resolved through autoload vectors. This causes the call to the 
subroutine to transfer control first to the autoload routine, 
allowing it to check and load any needed overlay segments before 
transferring control to the virtual address of the subroutine. 



Data References 

The safest place for all data is in the root segment. Data 
placed in an overlay segment is only accessible when the overlay 
segment is loaded and the reference is resolved directly. This 
means that with manual load, the data is accessible when the 
segment is loaded. 

With autoload, on the other hand, it's not that simple. 
References out from the root are usually not resolved directly, 
but through autoload vectors. For example, the reference to the 
global symbol A, a data label, is resolved to the label of an 
autoload vector within the same overlay segment. The actual 
virtual address of A is a value within the autoload vector. 
Therefore, a reference to A references the autoload vector, not 
the data itself. in addition, a reference to A does not cause the 
overlay segment to be loaded. It is loaded only on a call to a 
subroutine. Although there are some ways with autoload to get 
references resolved directly, it is difficult. 

With disk-resident overlays, another problem arises with any 
data changed at run time. If the data is in an overlay segment, 
it is reinitialized every time the segment is reloaded from disk, 
since the original copy of the code is reloaded. This problem 
occurs with both manual load and autoload. 
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The Task Builder normally combines together allocations for 
Psects of the same name. If the Psects have the local (LCL) 
attribute, combining is only done within a single overlay segment. 
If the Psects have the global (GBL) attribute, combining is done 
across overlay segment boundaries. For psects with the GBL 
attribute, by default, these allocations are collected in the 
segment specifying the Psect which is closest to the root segment. 
Therefore, if the Psect MYDATA is specified in the root segment 
and also in one or more overlay segments, the complete allocation 
is placed in the root segment. The OVR attribute tells the Task 
Builder to begin both allocations at the same virtual address. 
Consider Example 2 above. The local symbol M, defined locally in 
the overlay segment, corresponds to the beginning of the Psect in 
the root segment, the address of the first 2. The instruction INC 
M+2 again increments the second 2 to a 3. 

See Appendix E for additional information on how the Task 
Builder uses the various psect attributes. Also see section 3.2.4 
(on Allocation of Program Sections in a Multisegment Task) in the 
RSX-1 1M/M-PLUS Task Builder Manual for a description of how the 
Task Builder allocates Psects in an overlaid task. 

Two other methods can be used to place in the root a Psect 
which is not defined in the root. If a Psect has the SAV 
attribute, the Task Builder automatically places that psect 1 s 
allocation in the root. If the Psect does not have the SAV 
attribute, then the .PSECT Overlay Descriptor Language statement 
can be used to specify placement of a particular psect in the 
root, overriding the default placement. See section 3.4.5 (on the 
.PSECT Directive) in the RSX-1 1M/M-PLUS Task Builder Manual for an 
example of the use of .PSECT ODL directive. 

Example 6-6 is a more complex example of the use of overlays. 

It shows the use of both techniques for placing data in the root 

and referencing it from overlay segments. The program calling 
sequence is shown below. 
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following notes are keyed to the example. 

The psect OTHER is set up for using overlaid Psects to 
reference the data. Since it is defined in the root, the 
entire allocation for OTHER is in the root segment. 0P1 , 
0P2, and ANS can be just locally defined, since the 
overlay segments define the locations as offsets from the 
start of the psect. On the other hand, global symbols can 
be used instead, if desired. The data is an argument 
block for a call to $EDMSG. 

The references to the data from overlay segment J0B1 are 
set up by specifying the Psect OTHER, then defining local 
symbols. .BLKW statements are used because you are just 
defining symbols and offsets. The local symbols NUM1, 
NUM2, and SUM correspond to 0P1 , 0P2 , and ANS, 
respectively, in MAIN. 

The references to the data from overlay segment JOBXX are 
set up in a similar way. This time the same local symbols 
0P1 , 0P2 , and ANS are used again. 

The references to the data from overlay segment A are also 
set up in a similar way. This time only the starting 
address of the argument block is needed. 

The grand total and the ASCII operand (for $ EDMSG) are 
defined with the global symbols TOT and OP. 

The reference to TOT and OP in J0B1, and JOBXX, are 
automatically resolved directly. No special coding is 
needed in the referencing segment. TOTAL also references 
TOT, this time from the root segment (because TOTAL is 
also in the root segment) . 

Note that data which is pure (read-only) and referenced 
within the overlay segment only, causes no problems when 
placed in an overlay segment. The references are direct 
and the data is only referenced while the segment is 
loaded . 

The input buffer for the job number typed in by the 
operator, and the output buffer for displaying an 
operation's results are contained in an overlay segment 
and changed at run time. However, since the data is 
accessed only from within the overlay segment, and only 
while the segment is still loaded, no problems result. 
If, in fact, the MAIN segment referenced this data after a 
call to B was made, it would no longer work correctly 
because on reload, the data is reinitialized. 
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53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 



5 Set up for loop 



MOV #3vR4 

LOOP: GI0W*C I0»WVB»5>l»»>r 

CLR ANS 

C AL. L. A 

SOB R4>L00P 

QI0W*C IQ*UVB>5fl> r 9 > 

CALL TOTAL 



QI0W$C 
EXIT*S 
♦ END START 



t Counter 
<MES3>LMES3>40> ? Write MES3 
i Clear answer in case 
i of no operation 
t Call subroutine A 
? Decrement counter and 
r loop back until done 
<MES4*LMES4y40> t Write MES4 
r Call routine to 
9 display grand total 
I0»Wv"B>5> If 9 9 y<MES5rLMES5T40> ? Write MESS 
i Exit 



1 

2 
3 
4 

5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
"19 
20 
21 
^2 
23 
24 
25 
26 
'27 
20 
.29 
30 



♦TITLE i 
♦ I DENT 
♦ENABLE 



/01/ 
LC 



9 Enable lower case 



9 FILE A»MAC 



9 This subroutine displays a message and then asks which 

9 of two Jobs to do^ It calls the appropriate subroutine 

9 to do the Job? displays the results 9 and then returns 

9 to the main prog ram ♦ 



arg: 



MES * 



pmes: 

EMES ♦ 
0FMT i 

obuff: 

BUFF ♦ 



♦ MCALL 

♦ NLIST 

♦ PSECT 

♦ BLKW 

♦PSECT 
♦ASCII 

♦ ASCI I 
LMES=.- 

♦ ASCI I 
LPMES** 
♦ASCII 
LEMES** 
♦ASCIZ 

♦ BLKB 

♦ BLKB 

♦ EVEN 



QI0W*C»QI0W*S 

BEX 



9 System macros 
i Do not list binary 
i extensions 
OTHER D 9 GBL 9 VR 9 REL. 9 RW i PSECT with data 
4 9 Set address for start 

9 of argument block 
9 Back to blank PSECT 
<11>/SEGMENT A IS NOW LOADED* SUBR0UTIN/ 
/E A IS EXECUTING ♦ / 
MES 

<11>/D0 YOU WANT TO DO JOB 1 OR JOB 2? / 
-PMES 

<15><11>/N0 SUCH JOB* SORRY*/ 
—EMES 

<11>/%D %A ZD = %IU%N/ 

100* 9 Buffer for display of 

y Job results 
1 i Buffer for input char 

9 Move to word boundary 



Example 6-6 Complex Example Using Overlays (Sheet 2 of 6) 
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©I 27 

|_28 



e 
o 



29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 



MES * 



J0B1 



♦ ASCI I 
♦ASCII 
♦ASCII 
LMES- + - 

♦ EVEN 

♦ LIST 



<15><11><11>/SEGMENT J0B1 IS NOW LOADED ♦/ 
< 1 5>< 1 2>< 1 .1. X 1 1 >/SUBROUT I NE JOB 1 I S EX/ 
/ECUTING ♦ / 
•MES 



MOM 
ADD 
ADD 
MOV 

RETURN 
♦ END 



BEX 



9 List binary extensions 



Q IGW*C 1 ♦ WVB 9 5 9 1 99 9 9 <MES 9 LMES 9 A0> 



NUMlySUM 
NUM2ySUM 
SUM? TOT 
# ' + 9 OP 



Display 
9 message 
First operand to ans 
Add in other operand 
Add this answer to total 
Move operand for output 

display 
Return 



3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
'16 
17 
18 
19 
20 
L21 
22 
93 

24 
25 

" 26 
27 

.28 
29 
30 
31 



♦TITLE JOBXX 
♦I DENT /01/ 
♦ENABL LC 

FILE JOBXX* MAC 



9 Enable lower case 



This subroutine performs a multiplication operation ♦ 
It is assumed that local symbols 0P1? 0P2 3nd ANS 
correspond to the same local symbols in MAIN + The 
global symbol TOT? defined in MAIN* is the address 
where the grand total is maintained ♦ 



0P1 ♦ 



0P2i 
ANS ♦ 



MES! 



♦ MCALL 
♦NLIST 

♦PSECT 

♦ BLKW 

♦ BLKW 

♦ BLKW 

♦ BLKW 

♦ PSECT 

♦ BLKW 

♦ASCII 
♦ASCII 

♦ ASCII 
LMES=»- 

♦ EVEN 

♦ LIST 



QIOWSC 
BEX 

OTHER 
1 

1 

1 
1 



9 External system macros 
9 Do not list binary 
9 extensions 
D 9 GBL 9 OVR 9 REL 9 RW ? Data PSECT 
9 1st operand 
9 Address of operation 
9 in ASCII 
9 2nd operand 
9 Answer 



9 Back to blank PSECT 
1 024 ♦ #2 9 Leave space to make 

9 module larger 
<15X11X11>/SEGMENT JOBXX IS NOW/ 
/ LOADED ♦ /< 15X 1 2X 1 1 X 1 1 > 
/SUBROUTINE J0B2 IS EXECUTING*/ 
•MES 



BEX 



9 List binary extensions 
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e 



1 ♦TITLE B 

2 ♦ I DENT /Ol/ 

3 *ENABL LC y Enable lower case 

4 J + 

5 5 FILE B.MAC 

6 v 

7 » This subroutine displays a message and returns 

8 y - 

9 *MCALL GIGW$C y External system macros 
.10 *NLIST BEX i Do not list binary 

■i2 HES: .ASCII <11>/SEGMENT B Is'nO^S^SuBROUTINE/ 

13 ♦ASCII /BIS EXECUTING*/ 

""14 LMES = ♦ - MES 

15 .EVEN v Move to word boundary 

16 v 

1 7 B ♦ * Q 1 0W*C 1 ♦ WUB , 5 y 1 ? t > 9 <MES y LMES y 40> y D i sp lay 

18 ? message 

19 RETURN 9 Return 

20 ♦ END 

Run Session 
>RUN MRMAIN 

THE MAIN SEGMENT IS RUNNING AND WILL CALL A 

SEGMENT A IS NOW LOADED* SUBROUTINE A IS EXECUTING ♦ 
DO YOU WANT TO DO JOB 1 OR JOB 2? 1 

SEGMENT J0B1 IS NOW LOADED* 

SUBROUTINE J0B1 IS EXECUTING ♦ 
5 + 2 = 7 

THE MAIN SEGMENT WILL NOW CALL B 

SEGMENT B IS NOW LOADED* SUBROUTINE B IS EXECUTING* 
THE MAIN SEGMENT WILL NOW CALL A 

SEGMENT A IS NOW LOADED* SUBROUTINE A IS EXECUTING* 
DO YOU WANT TO DO JOB 1 OR JOB 2? 2 
SEGMENT JOBXX IS NOW LOADED ♦ 
SUBROUTINE J0B2 IS EXECUTING* 
5*2= 10 

THE MAIN SEGMENT WILL NOW CALL A 

SEGMENT A IS NOW LOADED* SUBROUTINE A IS EXECUTING* 
DO YOU WANT TO DO JOB 1 OR JOB 2? 2 

SEGMENT JOBXX IS NOW LOADED. 

SUBROUTINE J0B2 IS EXECUTING* 
5 * 2 = 10 

THE MAIN SEGMENT WILL NOW CALL A 

SEGMENT A IS NOW LOADED* SUBROUTINE A IS EXECUTING* 
DO YOU WANT TO DO JOB 1 OR JOB 2? 1 
SEGMENT J0B1 IS NOW LOADED* 
SUBROUTINE J0B1 IS EXECUTING* 
5 + 2 ~ 7 

THE MAIN SEGMENT WILL CALL TOTAL 
THE GRAND TOTAL IS 34* 

THE MAIN SEGMENT WILL NOW EXIT 
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A1 A2 B1 B2 



AO BO 

1 1 1 

Y 
I 

X 
I 

CNTRL 





A2 


B1 




A1 


B2 


BO 


AO 



Y 



X 



CNTRL 



TK-8635 

Figure 6-7 Task Without Co-Trees 
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Now do the tests/exercises for this module in the 
Tests/Exercises book. All but the first problem are lab problems. 
Check your answers against the provided solutions, either the 
on-line files (under UFD [202,2] or the printed copies in the 
Tests/Exercises book. 

If you think that you have mastered the material, ask your 
course administrator to record your progress on your personal 
Progress Plotter. You will then be ready to begin a new module. 

If you think that you have not yet mastered the material, 
return to this module for further study. 
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